Nginx PHP 空白頁面：fastcgi_param SCRIPT_FILENAME 詳細解析

問題現象

安裝 Nginx 後，HTML 正常顯示，PHP 檔案回傳空白頁面（HTTP 200），Nginx 與 PHP-FPM 日誌皆無錯誤。

根本原因

Nginx 未向 FastCGI 進程傳遞 SCRIPT_FILENAME 參數，PHP 解析器無法得知要執行的腳本路徑。

FastCGI 參數傳遞機制

根據 Nginx 官方文件，PHP 至少需要兩個參數才能運作：

fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name;
fastcgi_param QUERY_STRING    $query_string;

• SCRIPT_FILENAME：決定要執行的 PHP 腳本絕對路徑
• QUERY_STRING：包含 URL 參數（?a=1&b=2）

兩種設定位置

方案 A：直接在 location 區塊定義（推薦）

location ~ \.php$ {
    root           /var/www/html;
    fastcgi_pass   127.0.0.1:9000;
    fastcgi_index  index.php;
    fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
    include        fastcgi_params;
}

方案 B：統一在 fastcgi_params 檔案定義

# /etc/nginx/fastcgi_params
fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
fastcgi_param  REDIRECT_STATUS  200;

變數說明

常見誤區

1. ❌ 寫死路徑：fastcgi_param SCRIPT_FILENAME /scripts$fastcgi_script_name; — 遷移部署時會失效
2. ❌ 放在 include fastcgi_params 之後 — 會被後者覆蓋
3. ✅ 使用 $document_root$fastcgi_script_name 動態組合 — 可攜性最佳

除錯技巧

<?php
// 臨時建立 debug.php 驗證參數傳遞
var_dump($_SERVER['SCRIPT_FILENAME']);
var_dump($_SERVER['REQUEST_URI']);
?>

正確應顯示完整絕對路徑，如 /var/www/html/debug.php。