萬盛學電腦網

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

Nginx 代理 Apache 環境下配置 PHP 大文件上傳(100MB+)完整指南

場景背景

生產環境常見架構:Nginx 作為反向代理(處理靜態資源、SSL 終結、負載均衡),後端 Apache + PHP-FPM 處理動態業務。需支援 ≥100MB 大文件上傳,需協同調整三層配置:Nginx、PHP、應用層錯誤處理。

第一層:Nginx 配置 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 核心配置 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_OK0上傳成功—
UPLOAD_ERR_INI_SIZE1超過 upload_max_filesize檢查 php.ini
UPLOAD_ERR_FORM_SIZE2超過表單 MAX_FILE_SIZE檢查 HTML 隱藏字段
UPLOAD_ERR_PARTIAL3文件僅部分上傳網絡中斷、超時
UPLOAD_ERR_NO_FILE4未選擇文件前端驗證
UPLOAD_ERR_NO_TMP_DIR6缺少臨時目錄檢查 upload_tmp_dir 權限
UPLOAD_ERR_CANT_WRITE7寫入磁盤失敗磁盤滿、權限、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] ?? '未知上傳錯誤');
}

// 後續業務邏輯:移動文件、驗證類型、入庫記錄等
?>

進階優化建議

  1. 分片上傳:超大文件(>500MB)建議前端分片,後端合併,突破單次請求限制並支援斷點續傳。
  2. 異步處理:上傳完成即返回,異步隊列處理病毒掃描、格式轉換、縮略圖生成等耗時任務。
  3. 對象存儲直傳:生產環境建議使用 OSS/S3 簽名直傳,減輕應用伺服器 I/O 壓力。
  4. 監控告警:監控 413、504、上傳失敗率,及時發現配置不足或異常流量。

總結

大文件上傳是「木桶效應」:Nginx、PHP、應用代碼、磁盤 I/O、網絡帶寬任一環節配置不足即會失敗。按「由外而內、由基礎到業務」的順序逐層驗證,配合完善的錯誤碼映射與用戶提示,即可構建穩健的大文件上傳能力。

copyright © 萬盛學電腦網 all rights reserved