Debian 13 安裝Nginx官方版後，手動建立PHP FastCGI配置

Debian 13 安裝Nginx官方版後，手動建立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.4-fpm




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



若服務未啟動，請先執行
systemctl enable --now php8.4-fpm



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


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



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


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



建立 fastcgi-php.conf
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_ADDR        $remote_addr;
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

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

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

REDIRECT_STATUS 設為 200，讓PHP-FPM接受由Nginx轉發的請求 (必要參數，缺少時某些PHP-FPM設定會拒絕請求)


SCRIPT_FILENAME 若設定為空值或錯誤路徑，會導致PHP-FPM回傳 File not found 錯誤，這是最常見的配置問題





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

確認 fastcgi_params 是否存在

ls /etc/nginx/fastcgi_params


若已存在：可保留，但需確認其內容是否與 fastcgi.conf 一致 (Nginx官方版的 fastcgi_params 可能缺少 SCRIPT_FILENAME，這是與 fastcgi.conf 的主要差異)

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



注意：若你的 server block 中使用 include fastcgi_params;，請確保該檔案的內容與 fastcgi.conf 一致，否則可能造成 SCRIPT_FILENAME 遺漏，導致PHP-FPM無法找到要執行的腳本






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


重新載入Nginx

nginx -t



成功時應顯示
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
這時可以重新載入Nginx



重新載入Nginx
systemctl reload nginx



重開機
reboot



--------------------------------
重開機驗證配置是否持續有效
--------------------------------

重開機後，再次確認


確認Nginx配置語法

nginx -t




確認Nginx服務狀態
systemctl status nginx


應顯示 Active: active (running)





確認PHP-FPM服務狀態 (依實際版本調整)
systemctl status php8.4-fpm


應顯示 Active: active (running)





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

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

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

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

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

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

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