萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 檔案上傳完整指南:$_FILES 處理、驗證、安全與最佳實務

$_FILES 結構解析


    
    


// $_FILES['avatar'] 結構
[
    'name'     => 'photo.jpg',      // 原始檔名
    'type'     => 'image/jpeg',     // MIME 類型 (瀏覽器提供,不可信)
    'tmp_name' => '/tmp/phpXyz123', // 暫存檔路徑
    'error'    => 0,                // 錯誤代碼 (0=成功)
    'size'     => 2048576,          // 檔案大小 (bytes)
]

錯誤代碼對照

常數值說明
UPLOAD_ERR_OK0成功
UPLOAD_ERR_INI_SIZE1超過 php.ini upload_max_filesize
UPLOAD_ERR_FORM_SIZE2超過表單 MAX_FILE_SIZE
UPLOAD_ERR_PARTIAL3部分上傳
UPLOAD_ERR_NO_FILE4未選擇檔案
UPLOAD_ERR_NO_TMP_DIR6缺少暫存目錄
UPLOAD_ERR_CANT_WRITE7寫入磁碟失敗
UPLOAD_ERR_EXTENSION8PHP 擴展中斷

核心處理流程

<?php
function handleUpload(array $file, array $options = []): array {
    // 1. 檢查錯誤代碼
    if ($file['error'] !== UPLOAD_ERR_OK) {
        throw new RuntimeException('上傳失敗,錯誤代碼: ' . $file['error']);
    }
    
    // 2. 檢查檔案大小
    $maxSize = $options['max_size'] ?? 2 * 1024 * 1024; // 2MB
    if ($file['size'] > $maxSize) {
        throw new RuntimeException('檔案過大,限制 ' . ($maxSize/1024/1024) . 'MB');
    }
    
    // 3. 驗證 MIME 類型 (使用 finfo,不可信 $_FILES['type'])
    $allowedMimes = $options['allowed_mimes'] ?? [
        'image/jpeg', 'image/png', 'image/gif', 'image/webp'
    ];
    $finfo = new finfo(FILEINFO_MIME_TYPE);
    $mime = $finfo->file($file['tmp_name']);
    if (!in_array($mime, $allowedMimes, true)) {
        throw new RuntimeException('不支援的檔案類型: ' . $mime);
    }
    
    // 4. 驗證副檔名對應
    $extMap = [
        'image/jpeg' => 'jpg',
        'image/png'  => 'png',
        'image/gif'  => 'gif',
        'image/webp' => 'webp',
    ];
    $ext = $extMap[$mime] ?? 'bin';
    
    // 5. 產生安全檔名
    $filename = bin2hex(random_bytes(16)) . '.' . $ext;
    
    // 6. 確保上傳目錄存在
    $uploadDir = $options['upload_dir'] ?? __DIR__ . '/uploads';
    if (!is_dir($uploadDir)) {
        mkdir($uploadDir, 0755, true);
    }
    
    $destPath = $uploadDir . DIRECTORY_SEPARATOR . $filename;
    
    // 7. 移動檔案 (move_uploaded_file 會檢查是否為合法上傳檔案)
    if (!move_uploaded_file($file['tmp_name'], $destPath)) {
        throw new RuntimeException('檔案移動失敗');
    }
    
    // 8. 可選:產生縮圖、加浮水印、掃毒等
    if ($options['make_thumb'] ?? false) {
        createThumbnail($destPath, $uploadDir . '/thumb_' . $filename);
    }
    
    return [
        'filename' => $filename,
        'path' => $destPath,
        'url' => '/uploads/' . $filename,
        'mime' => $mime,
        'size' => $file['size'],
    ];
}

// 使用
try {
    $result = handleUpload($_FILES['avatar'], [
        'max_size' => 5 * 1024 * 1024,
        'allowed_mimes' => ['image/jpeg', 'image/png', 'image/webp'],
        'make_thumb' => true,
    ]);
    echo json_encode(['success' => true, 'data' => $result]);
} catch (RuntimeException $e) {
    echo json_encode(['success' => false, 'message' => $e->getMessage()]);
}
?>

安全性關鍵點

  1. never trust $_FILES['type']:必須用 finfo 或 getimagesize() 驗證真實類型
  2. 檔名隨機化:防止覆蓋、路徑遍歷、執行惡意腳本
  3. 上傳目錄不可執行 PHP:
    # .htaccess (Apache)
    
        Order Allow,Deny
        Deny from all
    
    # 或 Nginx
    location /uploads/ {
        location ~ \.php$ { return 403; }
    }
  4. 限制上傳大小:php.ini upload_max_filesize、post_max_size、表單 MAX_FILE_SIZE、程式碼三重防護
  5. 掃毒整合:ClamAV clamscan 或 VirusTotal API
  6. 圖片重新處理:GD/Imagick 重新編碼可移除嵌入惡意代碼

多檔案上傳



foreach ($_FILES['photos']['tmp_name'] as $index => $tmpName) {
    $file = [
        'name' => $_FILES['photos']['name'][$index],
        'type' => $_FILES['photos']['type'][$index],
        'tmp_name' => $tmpName,
        'error' => $_FILES['photos']['error'][$index],
        'size' => $_FILES['photos']['size'][$index],
    ];
    // 呼叫 handleUpload($file)
}

大檔案分塊上傳 (Resumable)

  • 前端:Uppy、Dropzone、Plupload 切片
  • 後端:合併分塊、斷點續傳、進度追蹤
  • 考慮使用 tus.io 開放協定實作

php.ini 關鍵設定

 upload_max_filesize
max_file_uploads = 20      ; 同時上傳檔案數上限
upload_tmp_dir = /tmp/php/uploads
max_execution_time = 300   ; 大檔案需較長時間
memory_limit = 256M

進階:串流直傳雲端儲存 (S3/GCS)

putObject([
    'Bucket' => 'my-bucket',
    'Key' => 'uploads/' . $filename,
    'Body' => fopen($_FILES['file']['tmp_name'], 'r'),
    'ContentType' => $mime,
    'ACL' => 'private',
]);
copyright © 萬盛學電腦網 all rights reserved