PHP 檔案上傳 php.ini 關鍵參數完整調校指南

前言

檔案上傳能否順利完成、大小限制、暫存路徑、執行逾時，全由 php.ini 掌控。本文系統整理 7 大核心參數、修改生效流程、多環境定位技巧、Nginx/Apache 協同配置，並提供生產環境建議值速查表。

七大核心參數詳細解析

參數關係圖（必須滿足的不等式）

memory_limit
    ≥ post_max_size
        ≥ upload_max_filesize
            ≥ 單檔實際大小

max_input_time ≥ 上傳耗時（受網速影響）
max_execution_time ≥ 處理耗時（含移動、縮圖、掃毒）

修改生效完整流程

1. 定位正確 php.ini：

   # CLI
   php --ini
   # FPM
   php-fpm -i | grep 'Loaded Configuration File'
   # 或建立 info.php
   <?php phpinfo(); ?>

2. 編輯參數：找到對應行，修改數值，移除前綴 ; 註解。
3. 重載服務：

   # PHP-FPM
   systemctl reload php-fpm
   # Apache (mod_php)
   systemctl reload apache2
   # Nginx + FPM 僅需 reload php-fpm

4. 驗證生效：再次 phpinfo() 或 php -i | grep upload_max_filesize 確認。

常見坑點：修改不生效的 5 大原因

生產環境建議配置範本（10MB 單檔上傳場景）

; /etc/php/8.2/fpm/php.ini
file_uploads = On
upload_tmp_dir = /var/tmp/php_upload
upload_max_filesize = 10M
post_max_size = 12M
memory_limit = 256M
max_execution_time = 120
max_input_time = 120

; 針對大檔上傳可考慮啟用
; session.gc_maxlifetime = 7200
; opcache.enable = 1

目錄權限設定（關鍵步驟）

# 建立暫存目錄
mkdir -p /var/tmp/php_upload
chown www-data:www-data /var/tmp/php_upload
chmod 1777 /var/tmp/php_upload  # sticky bit：只有擁有者能刪除自己的檔案

# 上傳落地目錄（Webroot 外）
mkdir -p /var/www/uploads
chown www-data:www-data /var/www/uploads
chmod 755 /var/www/uploads

進階：.user.ini 覆蓋單目錄設定（共享主機適用）

若無權修改主 php.ini，可在專案根目錄建立 .user.ini（需 user_ini.filename = ".user.ini"）：

upload_max_filesize = 20M
post_max_size = 25M
max_execution_time = 180
max_input_time = 180

生效延遲 user_ini.cache_ttl 秒（預設 300 秒），修改後需等待或重載 FPM。

總結

php.ini 上傳參數調校核心在於 「記憶體 ≥ POST ≥ 單檔、時間足夠接收與處理、暫存目錄獨立安全、Web 伺服器同步放寬」。建立標準化配置範本、納入基礎設施即代碼（IaC），新環境部署一鍵套用，避免「本地測試正常、上線失敗」的經典坑。