萬盛學電腦網

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

PHP 檔案上傳 php.ini 核心配置詳解:上傳限制、暫存目錄、效能與安全調優

前言

PHP 檔案上傳行為由 php.ini 多項指令聯動控制。誤解配置關係是導致「明明設定了大小限制卻不生效」、「大檔上傳失敗」的主因。本文系統解析每項指令、相互制約關係、環境別建議值與除錯清單。

一、核心上傳相關指令對照表

指令預設值可變範圍說明關鍵影響
file_uploadsOnPHP_INI_SYSTEM總開關,關閉則 $_FILES 永遠為空必須 On
upload_max_filesize2MPHP_INI_PERDIR單一檔案最大值受限於 post_max_size
post_max_size8MPHP_INI_PERDIRPOST 請求主體總大小上限 (含所有表單欄位+檔案)必須 ≥ upload_max_filesize
max_file_uploads20PHP_INI_SYSTEM單次請求最大檔案數量多檔上傳需調大
upload_tmp_dir系統預設PHP_INI_SYSTEM暫存目錄路徑需可寫、權限 1777、獨立分區防磁碟滿
max_execution_time30PHP_INI_ALL腳本最大執行秒數大檔上傳+處理需調大
max_input_time60PHP_INI_PERDIR解析 POST/GET 輸入資料最大秒數大檔上傳需調大
memory_limit128MPHP_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;
; 搭配分片上傳 / 直傳雲端儲存

四、常見配置錯誤與排查

1. 設定了 upload_max_filesize = 100M 但上傳 50M 失敗

原因: post_max_size (預設 8M) 小於檔案大小。PHP 在解析 POST 時直接截斷,$_FILES['error'] = UPLOAD_ERR_INI_SIZE (1)。

修正: post_max_size = 110M (大於 upload_max_filesize)。

2. Nginx 返回 413 Request Entity Too Large

原因: Nginx client_max_body_size 預設 1M,在 PHP 之前攔截。

修正: nginx.conf 中 http { client_max_body_size 100M; } 或 server/location 區塊設定。

3. Apache 返回 500 / 413

原因: LimitRequestBody (預設 0 無限制,但可能被模組覆蓋) 或 mod_security 規則。

排查: 檢查 httpd.conf、.htaccess、ModSecurity 規則。

4. 上傳成功但 $_FILES 為空 / error=4

原因: file_uploads = Off、表單缺少 enctype="multipart/form-data"、upload_tmp_dir 不可寫、open_basedir 限制。

5. 修改 php.ini 重啟後不生效

  • 確認編輯的是正確檔案:php --ini 或 phpinfo() 顯示 Loaded Configuration File
  • PHP-FPM 需重啟 systemctl restart php-fpm (非 reload)
  • Apache 模組需 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

六、執行期動態調整 (ini_set)

<?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 等
?>

七、除錯檢查清單

  1. php -i | grep -E 'upload_max_filesize|post_max_size|file_uploads|upload_tmp_dir'
  2. phpinfo() 確認生效值 (Local Value vs Master Value)
  3. 測試上傳略小於限制、等於限制、略大於限制的檔案
  4. 檢查 $_FILES['error'] 代碼對應
  5. 檢查 Nginx/Apache 錯誤日誌
  6. 確認 upload_tmp_dir 存在、權限 1777 (drwxrwxrwt)、磁碟空間充足
  7. 大檔測試:監控 memory_get_peak_usage()、執行時間

八、總結

PHP 檔案上傳配置是多層疊加的限制鏈:Nginx/Apache → post_max_size → upload_max_filesize → max_file_uploads → max_input_time/max_execution_time/memory_limit。任何一環過緊都會導致失敗。掌握關係圖、依環境調整、建立監控告警,才能確保上傳功能穩定運行。

copyright © 萬盛學電腦網 all rights reserved