Nginx + PHP-FPM 空白頁面終極排查指南

常見症狀

• HTML 靜態頁面正常，PHP 頁面回傳空白內容
• HTTP 狀態碼 200 OK，無錯誤訊息
• Nginx 與 PHP-FPM 錯誤日誌皆無異常紀錄

核心原因

Nginx 未正確傳遞 SCRIPT_FILENAME 參數給 PHP-FPM，導致 PHP 不知道要執行哪個腳本檔案。

解決方案：修正 Nginx 設定

location ~ \.php$ {
    root           /var/www/html;
    fastcgi_pass   127.0.0.1:9000;
    fastcgi_index  index.php;
    
    # 關鍵：必須在 include fastcgi_params 之前定義
    fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
    
    include        fastcgi_params;
}

為什麼預設 fastcgi_params 不夠？

官方 fastcgi_params 僅包含通用參數，不含 SCRIPT_FILENAME。此參數由部署環境決定，必須在站點設定中明確指定。

完整必要參數對照

替代寫法：修改 fastcgi_params 檔案

# /etc/nginx/fastcgi_params 追加
fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
fastcgi_param  REDIRECT_STATUS  200;  # PHP --enable-force-cgi-redirect 時需求

驗證步驟

1. 建立 phpinfo.php：<?php phpinfo(); ?>
2. 瀏覽器訪問，確認顯示 PHP 版本資訊而非空白
3. 檢查 $_SERVER['SCRIPT_FILENAME'] 是否為正確絕對路徑

其他可能原因快速排查

• PHP-FPM 未啟動：systemctl status php-fpm
• 權限問題：Nginx worker 進程需讀取 PHP 檔案權限
• open_basedir 限制：檢查 php.ini 設定
• PHP 致命錯誤但 display_errors=Off：啟用錯誤日誌 log_errors=On