自 PHP 4.2.0 起,$_FILES 陣列會包含 error 鍵,對應上傳過程的錯誤代碼。透過 $_FILES['userfile']['error'] 即可取得。以下為完整對照表:
| 常數名稱 | 數值 | 說明 | 引入版本 |
|---|---|---|---|
UPLOAD_ERR_OK |
0 | 上傳成功,無錯誤 | PHP 4.2.0+ |
UPLOAD_ERR_INI_SIZE |
1 | 上傳檔案超過 php.ini 的 upload_max_filesize 限制 |
PHP 4.2.0+ |
UPLOAD_ERR_FORM_SIZE |
2 | 上傳檔案超過 HTML 表單 MAX_FILE_SIZE 隱藏欄位指定的值 |
PHP 4.2.0+ |
UPLOAD_ERR_PARTIAL |
3 | 檔案只有部分被上傳(網路中斷或客戶端取消) | PHP 4.2.0+ |
UPLOAD_ERR_NO_FILE |
4 | 沒有檔案被上傳(使用者未選擇檔案) | PHP 4.2.0+ |
UPLOAD_ERR_NO_TMP_DIR |
6 | 找不到暫存目錄(php.ini upload_tmp_dir 未設定或不可寫) |
PHP 4.3.10 / 5.0.3 |
UPLOAD_ERR_CANT_WRITE |
7 | 檔案寫入磁碟失敗(磁碟空間不足、權限問題) | PHP 5.1.0 |
UPLOAD_ERR_EXTENSION |
8 | PHP 延伸模組中斷上傳(如 file_uploads = Off) |
PHP 5.2.0 |
<?php
function getUploadErrorMessage(int $errorCode): string
{
$messages = [
UPLOAD_ERR_OK => '上傳成功',
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[$errorCode] ?? "未知錯誤代碼: $errorCode";
}
// 使用範例
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$error = $_FILES['file']['error'] ?? UPLOAD_ERR_NO_FILE;
if ($error !== UPLOAD_ERR_OK) {
die('上傳失敗:' . getUploadErrorMessage($error));
}
// 進一步驗證:檔案類型、大小、MIME、移動檔案...
}
php.ini 的 upload_max_filesize、post_max_size,以及表單 <input type="hidden" name="MAX_FILE_SIZE" value="...">max_execution_time、max_input_timeupload_tmp_dir 指向可寫入目錄file_uploads = On,檢查搭載的延伸模組(如 Suhosin)善用錯誤代碼能快速定位上傳失敗原因,提供使用者精準的回饋訊息。