php.ini 是 PHP 行為的總控制台。本文對官方 php.ini-dist (開發版默認配置) 的核心段落進行**中文逐行註釋、影響說明、生產環境建議值**，作為配置調優、故障排查、安全加固的桌面參考手冊。
文件結構與語法規則
- 分號
; 開頭 = 註釋
- 方括號
[Section] = 節標識 (如 [PHP], [Date], [MySQLi])
- 指令格式：
directive = value (大小寫敏感)
- 值類型：字符串、數值、常量 (
On/Off/True/False/Yes/No/None)、表達式 (E_ALL & ~E_NOTICE)
- 邏輯運算：
| (或), & (與), ~ (非), ! (取反)
- 查找順序：當前工作目錄 →
PHPRC 環境變量 → 編譯時指定路徑 (Windows 為系統目錄) → -c 參數覆蓋
核心段落詳細註釋
1. 語言選項
| 指令 | 默認 | 建議(生產) | 說明 |
|---|
engine | On | On | 總開關。Off 將禁用 PHP 解析，文件當文本下載 |
zend.ze1_compatibility_mode | Off | Off | PHP 4 兼容模式，已棄用，勿開啟 |
short_open_tag | On | Off | 允許 <? ?> 短標簽。**生產建議關閉**，防止與 XML 聲明衝突、提高可移植性，統一用 <?php |
asp_tags | Off | Off | ASP 風格 <% %>，已移除，勿用 |
precision | 12 | 14 | 浮點數顯示精度 (位數)，科學計算可調大 |
y2k_compliance | On | On | 強制 2000 年兼容，保留兼容性 |
output_buffering | Off | 4096 (或 On) | 輸出緩衝。**生產建議開啟 (4KB)**，允許在輸出 body 後發送 header/cookie，減少網絡交互，微幅提升性能。大文件下載可調大 |
output_handler | 空 | 空 | 全局輸出處理器 (如 mb_output_handler 轉碼)。**不建議全局設置**，改用代碼中 ob_start('handler') 顯式控制 |
2. 資源限制
| 指令 | 默認 | 建議(生產) | 說明 |
|---|
max_execution_time | 30 | 60-300 | 腳本最大執行秒數 (CLI 下無效)。長任務 (導入、報表、視頻轉碼) 需調大，或用 set_time_limit() 動態設置。0 = 無限制 (危險) |
max_input_time | 60 | 60-300 | 解析 POST/GET/文件上傳數據的最大秒數。大文件上傳需配合 upload_max_filesize 調大 |
memory_limit | 128M | 256M-512M | 單腳本最大內存。**視業務調整**：WordPress/Composer/大數據處理需 512M+。過小導致 OOM，過大掩蓋內存洩漏 |
post_max_size | 8M | 50M-200M | POST 數據最大體積，**必須 > upload_max_filesize**。含所有表單字段+文件 |
upload_max_filesize | 2M | 50M-200M | 單文件上傳上限。**生產必改**，否則 phpMyAdmin/附件上傳寸步難行 |
max_file_uploads | 20 | 20-100 | 單次請求最大文件數 |
3. 錯誤處理與日誌 (生產環境核心)
| 指令 | 默認 | 建議(生產) | 說明 |
|---|
error_reporting | E_ALL & ~E_NOTICE & ~E_STRICT & ~E_DEPRECATED | E_ALL & ~E_DEPRECATED & ~E_STRICT | 報告錯誤級別。**生產建議包含 E_NOTICE**，盡早發現未定義變量等隱患 |
display_errors | On | Off | **生產必須關閉**，防止敏感信息 (路徑、SQL、密鑰) 洩露給用戶 |
display_startup_errors | Off | Off | 啟動階段錯誤 (模塊加載失敗等) 不顯示 |
log_errors | Off | On | **生產必須開啟**，錯誤寫入日誌文件而非瀏覽器 |
log_errors_max_len | 1024 | 4096 | 單條錯誤日誌最大長度，防止截斷堆棧 |
error_log | 空 (系統日誌) | /var/log/php/error.log | **指定專用日誌文件**，便於輪轉、分析、告警。需確保目錄可寫 |
ignore_repeated_errors | Off | Off | 忽略重複錯誤。開啟可減少日誌噪音，但可能掩蓋持續性問題 |
track_errors | Off | Off | 將最後一個錯誤信息存入 $php_errormsg。已棄用，勿用 |
4. 安全相關
| 指令 | 默認 | 建議(生產) | 說明 |
|---|
expose_php | On | Off | **關閉隱藏 PHP 版本** (HTTP Header X-Powered-By: PHP/x.y.z)，減少指纹識別攻擊面 |
allow_url_fopen | On | Off | **禁用遠程文件打開** (fopen('https://...'), include 'https://...')，防止 RFI (遠程文件包含) 攻擊 |
allow_url_include | Off | Off | 禁用遠程文件包含 (更嚴格)，PHP 5.2+ 默認關閉 |
disable_functions | 空 | exec,passthru,shell_exec,system,proc_open,popen,curl_exec,curl_multi_exec,parse_ini_file,show_source,pcntl_exec,dl,assert | **禁用高危函數**，防止代碼執行漏洞利用。視業務微調 (如需要 curl_exec 可保留) |
disable_classes | 空 | 空 | 禁用特定類，少用 |
open_basedir | 空 | /var/www/:/tmp/:/var/tmp/ | **限制腳本可訪問目錄** (含 include/require/fopen/文件操作)。**生產必配**，防止目錄遍歷、越權讀寫。多目錄用冒號分隔 (Windows 用分號) |
5. 會話
| 指令 | 默認 | 建議(生產) | 說明 |
|---|
session.save_handler | files | files / redis / memcached | 存儲引擎。分布式環境**必須用 Redis/Memcached**，單機 files 可行 |
session.save_path | /tmp | /var/lib/php/sessions | 文件存儲路徑。**獨立目錄、權限 700、屬主 www-data**，防止會話劫持/清理衝突 |
session.gc_maxlifetime | 1440 | 1440-86400 | 會話數據生存秒數 (24min-1天)。配合 session.gc_probability/divisor 控制 GC 概率 |
session.cookie_httponly | Off | On | **Cookie 僅 HTTP 可訪問，JS 不可讀**，防 XSS 竊取 Session ID |
session.cookie_secure | Off | On (僅 HTTPS) | **僅 HTTPS 傳輸 Cookie**，防中間人竊取。全站 HTTPS 後必開 |
session.use_strict_mode | Off | On | **嚴格模式**：拒絕未初始化的 Session ID，防 Session Fixation 攻擊 |
session.sid_length | 32 | 32-256 | Session ID 長度，越長越安全 |
6. 數據庫 (MySQLi / PDO_MySQL)
| 指令 | 默認 | 建議 | 說明 |
|---|
mysqli.allow_local_infile | On | Off | 禁用 LOAD DATA LOCAL INFILE，防止任意文件讀取攻擊 |
mysqli.allow_persistent | On | On | 允許持久連接。高併發建議開啟，配合連接池 |
mysqli.max_persistent | -1 | 100-200 | 最大持久連接數，防止連接洩漏耗盡數據庫 |
mysqli.max_links | -1 | 200-500 | 最大總連接數 (含非持久) |
mysqli.default_port | 3306 | 3306 | 默認端口 |
pdo_mysql.default_socket | 空 | /var/run/mysqld/mysqld.sock | Unix Socket 路徑，本地連接比 TCP 快 20-30% |
7. 文件上傳
| 指令 | 默認 | 建議 | 說明 |
|---|
file_uploads | On | On | 總開關 |
upload_tmp_dir | 空 (系統臨時目錄) | /var/tmp/php_upload | **獨立上傳臨時目錄**，權限 700、屬主 www-data、掛載 noexec/nosuid 分區，防上傳腳本執行 |
upload_max_filesize | 2M | 參見資源限制 | — |
max_file_uploads | 20 | 20-100 | — |
生產環境最小化安全配置清單 (可直接套用)
; 安全核心
expose_php = Off
allow_url_fopen = Off
allow_url_include = Off
disable_functions = exec,passthru,shell_exec,system,proc_open,popen,curl_exec,curl_multi_exec,parse_ini_file,show_source,pcntl_exec,dl,assert
open_basedir = /var/www/:/tmp/:/var/tmp/:/var/lib/php/sessions/
; 錯誤處理
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /var/log/php/error.log
error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT
; 資源
memory_limit = 256M
max_execution_time = 60
post_max_size = 100M
upload_max_filesize = 100M
; 會話安全
session.save_handler = redis
session.save_path = "tcp://127.0.0.1:6379?auth=yourpass"
session.cookie_httponly = On
session.cookie_secure = On
session.use_strict_mode = On
session.gc_maxlifetime = 7200
; 上傳安全
upload_tmp_dir = /var/tmp/php_upload
file_uploads = On
; 性能
output_buffering = 4096
realpath_cache_size = 4096K
realpath_cache_ttl = 600
總結
php.ini 不是「配好即忘」的靜態文件，而是**隨業務演進、威脅變化、PHP 版本升級而持續調優的動態策略文件**建議：
- **版本控制**：將
php.ini 納入 Git 管理，每次修改留痕
- **環境差異化**：開發/測試/預發/生產 **四套差異化配置** (如
display_errors, memory_limit, open_basedir)
- **定期審計**：季度對照 官方指令列表、php.ini-production、CIS Benchmark 檢查遺漏/過時項
- **變更驗證**：修改後必跑
php -i | grep directive 驗證生效，並執行自動化測試套件
掌握這份註釋手冊，你就擁有了精準調控 PHP 行為的「基因編輯儀」——不再盲目複製粘貼，而是知其然、知其所以然。
