$_FILES 結構解析
// $_FILES['avatar'] 結構
[
'name' => 'photo.jpg', // 原始檔名
'type' => 'image/jpeg', // MIME 類型 (瀏覽器提供,不可信)
'tmp_name' => '/tmp/phpXyz123', // 暫存檔路徑
'error' => 0, // 錯誤代碼 (0=成功)
'size' => 2048576, // 檔案大小 (bytes)
]
錯誤代碼對照
| 常數 | 值 | 說明 |
| UPLOAD_ERR_OK | 0 | 成功 |
| UPLOAD_ERR_INI_SIZE | 1 | 超過 php.ini upload_max_filesize |
| UPLOAD_ERR_FORM_SIZE | 2 | 超過表單 MAX_FILE_SIZE |
| UPLOAD_ERR_PARTIAL | 3 | 部分上傳 |
| UPLOAD_ERR_NO_FILE | 4 | 未選擇檔案 |
| UPLOAD_ERR_NO_TMP_DIR | 6 | 缺少暫存目錄 |
| UPLOAD_ERR_CANT_WRITE | 7 | 寫入磁碟失敗 |
| UPLOAD_ERR_EXTENSION | 8 | PHP 擴展中斷 |
核心處理流程
<?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()]);
}
?>
安全性關鍵點
- never trust $_FILES['type']:必須用
finfo 或 getimagesize() 驗證真實類型
- 檔名隨機化:防止覆蓋、路徑遍歷、執行惡意腳本
- 上傳目錄不可執行 PHP:
# .htaccess (Apache)
Order Allow,Deny
Deny from all
# 或 Nginx
location /uploads/ {
location ~ \.php$ { return 403; }
}
- 限制上傳大小:php.ini
upload_max_filesize、post_max_size、表單 MAX_FILE_SIZE、程式碼三重防護
- 掃毒整合:ClamAV
clamscan 或 VirusTotal API
- 圖片重新處理: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',
]);