生產環境常見架構:Nginx 作為反向代理(處理靜態資源、SSL 終結、負載均衡),後端 Apache + PHP-FPM 處理動態業務。需支援 ≥100MB 大文件上傳,需協同調整三層配置:Nginx、PHP、應用層錯誤處理。
client_max_body_size在 nginx.conf 的 http、server 或 location 上下文中設置:
http {
# ... 其他配置
client_max_body_size 100m; # 允許客戶端請求體最大 100MB
# ...
}
關鍵點:預設為 1m,超過即返回 413 Request Entity Too Large。建議放在 http 層全局生效,或在具體 server/location 精細控制。
php.ini三大核心參數必須齊備,且 post_max_size ≥ upload_max_filesize:
; 執行時間無限制(大文件上傳耗時長)
max_execution_time = 0
; POST 數據總大小上限(含所有表單字段+文件)
post_max_size = 100M
; 單個上傳文件大小上限
upload_max_filesize = 100M
; 可選:內存限制(大文件處理可能需要更多記憶體)
memory_limit = 256M
; 可選:臨時文件目錄(確保可寫、空間充足)
; upload_tmp_dir = /tmp
常見坑:只改 upload_max_filesize 而忘記 post_max_size,導致大文件仍被截斷;或 max_execution_time 過短導致上傳中途超時。
$_FILES['error']上傳失敗時,$_FILES['file']['error'] 返回錯誤碼,需精準捕獲並友好提示:
| 常量 | 值 | 含義 | 排查方向 |
|---|---|---|---|
| UPLOAD_ERR_OK | 0 | 上傳成功 | — |
| UPLOAD_ERR_INI_SIZE | 1 | 超過 upload_max_filesize | 檢查 php.ini |
| UPLOAD_ERR_FORM_SIZE | 2 | 超過表單 MAX_FILE_SIZE | 檢查 HTML 隱藏字段 |
| UPLOAD_ERR_PARTIAL | 3 | 文件僅部分上傳 | 網絡中斷、超時 |
| UPLOAD_ERR_NO_FILE | 4 | 未選擇文件 | 前端驗證 |
| UPLOAD_ERR_NO_TMP_DIR | 6 | 缺少臨時目錄 | 檢查 upload_tmp_dir 權限 |
| UPLOAD_ERR_CANT_WRITE | 7 | 寫入磁盤失敗 | 磁盤滿、權限、inode 耗盡 |
<?php
$errorMap = [
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 => '文件寫入失敗,請聯繫管理員',
];
$errCode = $_FILES['file']['error'] ?? UPLOAD_ERR_NO_FILE;
if ($errCode !== UPLOAD_ERR_OK) {
throw new Exception($errorMap[$errCode] ?? '未知上傳錯誤');
}
// 後續業務邏輯:移動文件、驗證類型、入庫記錄等
?>
413、504、上傳失敗率,及時發現配置不足或異常流量。大文件上傳是「木桶效應」:Nginx、PHP、應用代碼、磁盤 I/O、網絡帶寬任一環節配置不足即會失敗。按「由外而內、由基礎到業務」的順序逐層驗證,配合完善的錯誤碼映射與用戶提示,即可構建穩健的大文件上傳能力。