手動建立 PHP FastCGI 設定檔

----------
前言
----------

本教學適用於 Debian 13 安裝 Nginx 官方版本後，手動建立PHP所需的FastCGI配置檔，確保PHP解析能正常運作



Nginx官方版 預設不包含 snippets/ 目錄與 fastcgi.conf，需要手動建立


目錄結構說明，手動建立以下兩個檔案


/etc/nginx/snippets/fastcgi-php.conf：PHP請求的FastCGI參數封裝 (供 server block 引用)


/etc/nginx/fastcgi.conf：FastCGI通用參數設定檔 (部分系統預設為 fastcgi_params)





------------------------------
確認PHP-FPM已安裝並運行
------------------------------

請先確認PHP-FPM已正確安裝且處於運行狀態，否則後續配置即使正確也無法正常解析PHP


確認PHP-FPM套件已安裝
dpkg -l | grep php8.3-fpm




確認PHP-FPM服務狀態
systemctl status php8.3-fpm




確認 socket 檔案存在 (後續 fastcgi_pass 會用到)
ls /run/php/php8.3-fpm.sock


重要：若 socket 不存在，代表PHP-FPM未正常啟動，需先排除該問題再繼續





------------------------------------------------------
建立 /etc/nginx/snippets/fastcgi-php.conf
------------------------------------------------------


建立目錄
mkdir -p /etc/nginx/snippets



建立
vi /etc/nginx/snippets/fastcgi-php.conf



貼上以下內容


fastcgi_split_path_info ^(.+\.php)(/.+)$;

set $path_info $fastcgi_path_info;

fastcgi_param PATH_INFO $path_info;

fastcgi_index index.php;

include fastcgi.conf;







儲存檔案並離開vi編輯器
按 Esc，輸入 :wq，按 Enter





說明：

fastcgi_split_path_info 用來解析像是 /index.php/foo 這類路徑

try_files 可避免惡意使用者直接呼叫未存在的PHP檔案

include fastcgi.conf 會載入建立的FastCGI參數檔





------------------------------------------
建立 /etc/nginx/fastcgi.conf
------------------------------------------


建立
vi /etc/nginx/fastcgi.conf



貼上以下內容


fastcgi_param  SCRIPT_FILENAME    $document_root$fastcgi_script_name;
fastcgi_param  QUERY_STRING       $query_string;
fastcgi_param  REQUEST_METHOD     $request_method;
fastcgi_param  CONTENT_TYPE       $content_type;
fastcgi_param  CONTENT_LENGTH     $content_length;

fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
fastcgi_param  REQUEST_URI        $request_uri;
fastcgi_param  DOCUMENT_URI       $document_uri;
fastcgi_param  DOCUMENT_ROOT      $document_root;
fastcgi_param  SERVER_PROTOCOL    $server_protocol;
fastcgi_param  REQUEST_SCHEME     $scheme;

fastcgi_param  HTTPS              $https if_not_empty;

fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
fastcgi_param  SERVER_SOFTWARE    nginx;

fastcgi_param  REMOTE_PORT        $remote_port;
fastcgi_param  REMOTE_USER        $remote_user;
fastcgi_param  SERVER_ADDR        $server_addr;
fastcgi_param  SERVER_PORT        $server_port;
fastcgi_param  SERVER_NAME        $server_name;

fastcgi_param  REDIRECT_STATUS    200;





儲存檔案並離開vi編輯器
按 Esc，輸入 :wq，按 Enter




關鍵參數說明：

SCRIPT_FILENAME 告知 PHP-FPM 要執行的完整檔案路徑，必須為 $document_root$fastcgi_script_name
設定錯誤會導致 File not found 錯誤，是最常見的配置問題

HTTPS 使用 if_not_empty，確保僅在 HTTPS 連線時才傳遞此參數，避免 HTTP 連線下 PHP 誤判為 HTTPS

REQUEST_SCHEME 傳遞 http 或 https，讓 PHP 應用程式正確判斷協定（在 CDN / 反向代理後面的部署尤為重要）

REDIRECT_STATUS 設為 200，讓 PHP-FPM 接受由 Nginx 轉發的請求。缺少時某些 PHP-FPM 設定會拒絕請求





---------------------------------
確認 fastcgi_params 是否存在
---------------------------------

確認 fastcgi_params 是否存在

ls /etc/nginx/fastcgi_params


若已存在：確認其內容，Nginx 官方版的 fastcgi_params 可能缺少 SCRIPT_FILENAME，這是與 fastcgi.conf 的主要差異

若不存在：可建立符號連結，或直接以 fastcgi.conf 的內容建立


注意：若你的 server block 中使用 include fastcgi_params;，請確保該檔案的內容與 fastcgi.conf 一致

否則可能造成 SCRIPT_FILENAME 遺漏，導致 PHP-FPM 無法找到要執行的腳本






-------------------------
測試語法與重新載入Nginx
-------------------------


重新載入
systemctl reload nginx



測試語法
nginx -t



成功應顯示
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful





--------------------------------
重開機驗證
--------------------------------



重開機
reboot



測試語法
nginx -t



確認Nginx服務狀態，應顯示 Active: active (running)
systemctl status nginx







確認PHP-FPM服務狀態，應顯示 Active: active (running)
systemctl status php8.3-fpm







----------------------
補充說明與常見遺漏
----------------------

忘記建立 snippets/ 目錄，導致 include 失敗

fastcgi_pass 未正確設定 (如 unix:/run/php/php8.3-fpm.sock)

未確認 PHP-FPM 是否已安裝與啟動

未檢查 fastcgi_params 與 fastcgi.conf 的差異，導致部分應用程式出現 PATH_INFO 錯誤

未考慮HTTPS情境下的 REQUEST_SCHEME 與 HTTPS 參數傳遞

未確認 $document_root 是否與 root 指令一致

Edited June 9Jun 9 by Jack