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 端口,实际端口可能不同。

nginx
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;
    }
}

预期结果

text
Nginx 将 /index.php 请求转发到 PHP-FPM
PHP-FPM 执行脚本并返回动态页面内容

fastcgi_pass 决定请求发送到哪个 PHP-FPM 服务,SCRIPT_FILENAME 决定 PHP-FPM 实际执行哪个文件。如果该参数错误,PHP-FPM 会找不到脚本。

处理入口文件和路径解析问题

生产环境中经常使用入口文件模式,例如所有请求进入 index.php,再由应用框架处理路由。此时需要配合 try_files 保证真实脚本路径正确。

nginx
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;
}

预期结果

text
访问 /user/profile
请求转入 /index.php
PHP 应用接收到原始查询参数并处理路由

使用 root 时,SCRIPT_FILENAME 通常可以使用 $document_root$fastcgi_script_name。如果使用 alias 或特殊目录映射,需要重新确认实际文件路径。

排查 PHP-FPM 转发失败

遇到 PHP 页面异常时,可以按照请求链路检查:先确认 Nginx 配置是否加载,再确认 PHP-FPM 是否监听,最后确认脚本文件权限。

bash
nginx -t
ss -lntp | grep 9000
ls -l /var/www/html/index.php

预期结果

text
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 拼接后的真实路径。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

连接 PHP-FPM

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通