Web 服务器与网关 / 系统课时
连接 PHP-FPM
连接 PHP-FPM
本节解决 Nginx 接收 PHP 请求后无法正确执行脚本的问题。通过配置 fastcgi_pass、脚本路径和 FastCGI 参数,让 Nginx 将动态请求交给 PHP-FPM 处理,并掌握常见路径与权限错误的定位方法。
学习目标
- 理解 Nginx 与 PHP-FPM 的请求转发关系。
- 掌握 fastcgi_pass、SCRIPT_FILENAME 等关键配置。
- 能够排查 PHP 入口文件和权限导致的 404、502 问题。
理解 Nginx 与 PHP-FPM 的协作方式
Nginx 本身不会执行 PHP 代码,它负责接收 HTTP 请求、匹配 PHP 文件路径,然后通过 FastCGI 协议把请求转发给 PHP-FPM。PHP-FPM 执行脚本后返回结果,Nginx 再响应给客户端。
当配置错误时,常见现象包括 PHP 源码被下载、返回 404、出现 502 Bad Gateway,原因通常集中在 FastCGI 地址、脚本路径和运行权限三个方向。
配置 fastcgi_pass 转发 PHP 请求
PHP 请求通常通过 location 匹配 .php 文件,并设置 FastCGI 参数。下面示例假设 PHP-FPM 监听本机 9000 端口,实际端口可能不同。
server {
listen 80;
server_name example.com;
root /var/www/html;
location ~ \.php$ {
include fastcgi_params;
fastcgi_pass 127.0.0.1:9000;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
}预期结果
Nginx 将 /index.php 请求转发到 PHP-FPM
PHP-FPM 执行脚本并返回动态页面内容fastcgi_pass 决定请求发送到哪个 PHP-FPM 服务,SCRIPT_FILENAME 决定 PHP-FPM 实际执行哪个文件。如果该参数错误,PHP-FPM 会找不到脚本。
处理入口文件和路径解析问题
生产环境中经常使用入口文件模式,例如所有请求进入 index.php,再由应用框架处理路由。此时需要配合 try_files 保证真实脚本路径正确。
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_pass 127.0.0.1:9000;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}预期结果
访问 /user/profile
请求转入 /index.php
PHP 应用接收到原始查询参数并处理路由使用 root 时,SCRIPT_FILENAME 通常可以使用 $document_root$fastcgi_script_name。如果使用 alias 或特殊目录映射,需要重新确认实际文件路径。
排查 PHP-FPM 转发失败
遇到 PHP 页面异常时,可以按照请求链路检查:先确认 Nginx 配置是否加载,再确认 PHP-FPM 是否监听,最后确认脚本文件权限。
nginx -t
ss -lntp | grep 9000
ls -l /var/www/html/index.php预期结果
nginx: configuration file ... test is successful
LISTEN ... 127.0.0.1:9000 ... php-fpm
-rw-r--r-- ... index.php如果出现 502,优先检查 PHP-FPM 是否启动或监听地址是否一致。如果出现 404,重点检查 SCRIPT_FILENAME 拼接后的真实路径。