萬盛學電腦網

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

PHP 檔案上傳錯誤代碼完整對照表

自 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、移動檔案...
}

常見排查重點

  • 錯誤 1/2:檢查 php.ini 的 upload_max_filesize、post_max_size,以及表單 <input type="hidden" name="MAX_FILE_SIZE" value="...">
  • 錯誤 3:通常為網路不穩、大檔案逾時,檢查 max_execution_time、max_input_time
  • 錯誤 6:設定 upload_tmp_dir 指向可寫入目錄
  • 錯誤 7:檢查磁碟空間、目錄權限、SELinux/AppArmor 限制
  • 錯誤 8:確認 file_uploads = On,檢查搭載的延伸模組(如 Suhosin)

善用錯誤代碼能快速定位上傳失敗原因,提供使用者精準的回饋訊息。

copyright © 萬盛學電腦網 all rights reserved