PHP 檔案上傳核心函數深度解析：is_uploaded_file 與 move_uploaded_file

兩大核心函數詳解

PHP 檔案上傳機制仰賴兩個關鍵函數，理解其差異與正確用法是建立安全上傳功能的基礎。

1. is_uploaded_file() — 確認檔案來源

用途：驗證檔案確實是透過 HTTP POST 上傳，而非本地檔案路徑偽造。

bool is_uploaded_file(string $filename)

回傳：成功上傳回 true，否則 false。

必要性：防止攻擊者利用變數覆蓋漏洞，偽造 $_FILES 內容竊取伺服器敏感檔案（如 /etc/passwd）。

2. move_uploaded_file() — 安全移動暫存檔

用途：將上傳的暫存檔移動到指定永久位置。

bool move_uploaded_file(string $filename, string $destination)

特性：

• 內建檢查：確認檔案是合法上傳檔（等同 is_uploaded_file）
• 原子性操作：跨分區時會複製後刪除來源
• 覆蓋行為：目標檔存在時會直接覆蓋

表單必要屬性

<form enctype="multipart/form-data" method="post" action="upload.php">
    <input type="hidden" name="MAX_FILE_SIZE" value="2000000">
    <input type="file" name="upfile">
    <input type="submit" value="上傳">
</form>

• enctype="multipart/form-data"：必要，否則 $_FILES 為空
• MAX_FILE_SIZE：客戶端提示上限（瀏覽器可能忽略），伺服端仍需驗證
• type="file"：啟用檔案選擇對話框

$_FILES 陣列結構完整說明

完整安全上傳類別實作

<?php
// FileUploader.php
class FileUploader {
    private $allowed_types = ['image/jpeg', 'image/png', 'image/gif', 'application/pdf'];
    private $max_size = 5 * 1024 * 1024; // 5MB
    private $upload_dir;
    
    public function __construct(string $upload_dir) {
        $this->upload_dir = rtrim($upload_dir, '/') . '/';
        if (!is_dir($this->upload_dir)) {
            mkdir($this->upload_dir, 0755, true);
        }
    }
    
    public function upload(string $field_name): array {
        if (!isset($_FILES[$field_name])) {
            return ['success' => false, 'error' => '欄位不存在'];
        }
        
        $file = $_FILES[$field_name];
        
        // 1. 基礎錯誤檢查
        if ($file['error'] !== UPLOAD_ERR_OK) {
            return ['success' => false, 'error' => $this->get_error_message($file['error'])];
        }
        
        // 2. 確認合法上傳檔案
        if (!is_uploaded_file($file['tmp_name'])) {
            return ['success' => false, 'error' => '非法檔案來源'];
        }
        
        // 3. 大小檢查
        if ($file['size'] > $this->max_size) {
            return ['success' => false, 'error' => '檔案過大'];
        }
        
        // 4. MIME 類型驗證（使用 finfo 避免偽造）
        $finfo = finfo_open(FILEINFO_MIME_TYPE);
        $mime = finfo_file($finfo, $file['tmp_name']);
        finfo_close($finfo);
        
        if (!in_array($mime, $this->allowed_types)) {
            return ['success' => false, 'error' => '檔案類型不允許'];
        }
        
        // 5. 產生安全檔名
        $ext = $this->get_extension($mime);
        $filename = bin2hex(random_bytes(16)) . ".{$ext}";
        $destination = $this->upload_dir . $filename;
        
        // 6. 移動檔案
        if (!move_uploaded_file($file['tmp_name'], $destination)) {
            return ['success' => false, 'error' => '檔案移動失敗'];
        }
        
        // 7. 設定安全權限
        chmod($destination, 0644);
        
        return [
            'success' => true,
            'filename' => $filename,
            'path' => $destination,
            'original_name' => $file['name'],
            'size' => $file['size'],
            'mime' => $mime
        ];
    }
    
    private function get_extension(string $mime): string {
        $map = [
            'image/jpeg' => 'jpg',
            'image/png' => 'png',
            'image/gif' => 'gif',
            'application/pdf' => 'pdf',
        ];
        return $map[$mime] ?? 'bin';
    }
    
    private function get_error_message(int $code): string {
        $messages = [
            UPLOAD_ERR_INI_SIZE => '超過 php.ini upload_max_filesize',
            UPLOAD_ERR_FORM_SIZE => '超過表單 MAX_FILE_SIZE',
            UPLOAD_ERR_PARTIAL => '檔案部分上傳',
            UPLOAD_ERR_NO_FILE => '未上傳檔案',
            UPLOAD_ERR_NO_TMP_DIR => '缺少暫存目錄',
            UPLOAD_ERR_CANT_WRITE => '寫入磁碟失敗',
            UPLOAD_ERR_EXTENSION => 'PHP 擴充套件中斷上傳',
        ];
        return $messages[$code] ?? '未知上傳錯誤';
    }
}

// 使用範例
$uploader = new FileUploader(__DIR__ . '/uploads');
$result = $uploader->upload('upfile');
if ($result['success']) {
    echo "上傳成功：{$result['path']}";
} else {
    echo "失敗：{$result['error']}";
}
?>

分離式架構：上傳頁面與處理邏輯

<!-- upload_form.php -->
<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>檔案上傳</title></head>
<body>
<h2>檔案上傳</h2>
<form action="save_upload.php" method="post" enctype="multipart/form-data">
    <label>選擇檔案：<input type="file" name="upfile" required></label>
    <button type="submit">上傳</button>
</form>
</body></html>

<?php
// save_upload.php
require_once 'FileUploader.php';
$uploader = new FileUploader(__DIR__ . '/uploads');
$result = $uploader->upload('upfile');
header('Content-Type: application/json');
echo json_encode($result);
?>

關鍵安全總結

1. 永遠使用 is_uploaded_file() 或 move_uploaded_file() 驗證來源
2. 使用 finfo 驗證真實 MIME 類型，不要信任 $_FILES['type']
3. 重命名檔案，避免原始檔名注入與覆蓋
4. 上傳目錄設定不可執行腳本
5. 限制檔案大小、類型、副檔名三重防護