March 16Mar 16 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 指令一致
Create an account or sign in to comment