PHP 檔案上傳行為由 php.ini 多項指令聯動控制。誤解配置關係是導致「明明設定了大小限制卻不生效」、「大檔上傳失敗」的主因。本文系統解析每項指令、相互制約關係、環境別建議值與除錯清單。
| 指令 | 預設值 | 可變範圍 | 說明 | 關鍵影響 |
|---|---|---|---|---|
file_uploads | On | PHP_INI_SYSTEM | 總開關,關閉則 $_FILES 永遠為空 | 必須 On |
upload_max_filesize | 2M | PHP_INI_PERDIR | 單一檔案最大值 | 受限於 post_max_size |
post_max_size | 8M | PHP_INI_PERDIR | POST 請求主體總大小上限 (含所有表單欄位+檔案) | 必須 ≥ upload_max_filesize |
max_file_uploads | 20 | PHP_INI_SYSTEM | 單次請求最大檔案數量 | 多檔上傳需調大 |
upload_tmp_dir | 系統預設 | PHP_INI_SYSTEM | 暫存目錄路徑 | 需可寫、權限 1777、獨立分區防磁碟滿 |
max_execution_time | 30 | PHP_INI_ALL | 腳本最大執行秒數 | 大檔上傳+處理需調大 |
max_input_time | 60 | PHP_INI_PERDIR | 解析 POST/GET 輸入資料最大秒數 | 大檔上傳需調大 |
memory_limit | 128M | PHP_INI_ALL | 腳本最大記憶體 | 圖片處理 (GD/Imagick) 需足夠記憶體 |
post_max_size vs upload_max_filesize | - | - | post_max_size 必須 > upload_max_filesize | 否則大檔被截斷,$_FILES['error']=1 |
Client Request (POST multipart/form-data)
│
▼
Web Server (Nginx/Apache) → client_max_body_size / LimitRequestBody
│
▼
PHP SAPI (FPM/Apache Module)
│
├─▶ post_max_size (總體大小閘門) ──✗ 超過 → $_POST/$_FILES 為空,error=1
│
├─▶ max_input_time (解析逾時) ──✗ 逾時 → 500/504
│
├─▶ max_file_uploads (檔案數量) ──✗ 超過 → 多餘檔案捨棄
│
▼
$_FILES['file']['tmp_name'] 寫入 upload_tmp_dir
│
├─▶ upload_max_filesize (單檔大小) ──✗ 超過 → error=1
│
▼
PHP Script 執行 (move_uploaded_file, 圖片處理...)
│
├─▶ max_execution_time (執行逾時)
│
├─▶ memory_limit (記憶體)
│
▼
完成
file_uploads = On
upload_max_filesize = 50M
post_max_size = 60M
max_file_uploads = 50
upload_tmp_dir = "/tmp/php_upload_dev"
max_execution_time = 120
max_input_time = 120
memory_limit = 512M
file_uploads = On
upload_max_filesize = 10M
post_max_size = 12M
max_file_uploads = 20
upload_tmp_dir = "/var/tmp/php_upload"
max_execution_time = 60
max_input_time = 60
memory_limit = 256M
file_uploads = On
upload_max_filesize = 500M
post_max_size = 512M
max_file_uploads = 10
upload_tmp_dir = "/mnt/upload_tmp" # 獨立掛載點,大容量、高 IOPS
max_execution_time = 300
max_input_time = 300
memory_limit = 1024M
; 搭配 Nginx client_max_body_size 512M;
; 搭配分片上傳 / 直傳雲端儲存
原因: post_max_size (預設 8M) 小於檔案大小。PHP 在解析 POST 時直接截斷,$_FILES['error'] = UPLOAD_ERR_INI_SIZE (1)。
修正: post_max_size = 110M (大於 upload_max_filesize)。
原因: Nginx client_max_body_size 預設 1M,在 PHP 之前攔截。
修正: nginx.conf 中 http { client_max_body_size 100M; } 或 server/location 區塊設定。
原因: LimitRequestBody (預設 0 無限制,但可能被模組覆蓋) 或 mod_security 規則。
排查: 檢查 httpd.conf、.htaccess、ModSecurity 規則。
原因: file_uploads = Off、表單缺少 enctype="multipart/form-data"、upload_tmp_dir 不可寫、open_basedir 限制。
php --ini 或 phpinfo() 顯示 Loaded Configuration Filesystemctl restart php-fpm (非 reload)systemctl restart httpd/apache2.user.ini、.htaccess php_value 覆蓋; 禁止危險函數
disable_functions = exec,passthru,shell_exec,system,proc_open,popen,curl_exec,curl_multi_exec,pcntl_exec,putenv,dl,assert,mail
; 限制檔案存取範圍
open_basedir = /var/www/html:/tmp:/var/tmp/php_upload:/usr/share/php
; Session 安全
session.cookie_secure = 1
session.cookie_httponly = 1
session.cookie_samesite = "Lax"
session.use_strict_mode = 1
; 隱藏 PHP 版本
expose_php = Off
; 錯誤不顯示、只記錄
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /var/log/php/php_error.log
<?php
// 僅能調整 PHP_INI_ALL / PHP_INI_PERDIR 指令
ini_set('max_execution_time', '300');
ini_set('memory_limit', '512M');
ini_set('upload_max_filesize', '50M'); // PHP_INI_PERDIR,在 .user.ini 或啟動前生效
ini_set('post_max_size', '60M'); // 同理
// 執行期無法修改 PHP_INI_SYSTEM 指令:
// file_uploads, upload_tmp_dir, max_file_uploads, enable_dl 等
?>
php -i | grep -E 'upload_max_filesize|post_max_size|file_uploads|upload_tmp_dir'phpinfo() 確認生效值 (Local Value vs Master Value)$_FILES['error'] 代碼對應upload_tmp_dir 存在、權限 1777 (drwxrwxrwt)、磁碟空間充足memory_get_peak_usage()、執行時間PHP 檔案上傳配置是多層疊加的限制鏈:Nginx/Apache → post_max_size → upload_max_filesize → max_file_uploads → max_input_time/max_execution_time/memory_limit。任何一環過緊都會導致失敗。掌握關係圖、依環境調整、建立監控告警,才能確保上傳功能穩定運行。