Nginx配置PHP站点详细教程

本文深入解析了Nginx与PHP-FPM协同配置中高频出现的502 Bad Gateway和504 Gateway Timeout等核心故障，直击通信失败、路径错配、超时设置不一致、权限不足、opcache缓存干扰及多Pool混淆等实战痛点，不仅揭示“连不上”与“等太久”的本质区别，更提供从进程验证、fastcgi_pass地址严格对齐、SCRIPT_FILENAME安全写法、超时参数双向同步、权限排查到opcache调试策略的一线可落地解决方案——无论你是刚搭建PHP站点的新手，还是正被诡异502折磨的运维人，都能在这里找到快速定位与根治问题的关键线索。

php-fpm 没连上，502 Bad Gateway 是最常见信号

nginx 和 PHP 之间不直接通信，必须靠 php-fpm 中转。出现 502 Bad Gateway，八成是 nginx 根本没把请求转给 php-fpm，或者转了但对方没响应。

先确认 php-fpm 进程在跑：systemctl status php-fpm（或 php8.1-fpm，版本号得对得上）。别只看服务名，ps aux | grep fpm 看实际进程更准。

再查 nginx 配置里 fastcgi_pass 指向是否匹配 php-fpm 的监听地址：

• 如果 php-fpm 配置的是 listen = /run/php/php8.1-fpm.sock，nginx 就得写 fastcgi_pass unix:/run/php/php8.1-fpm.sock;
• 如果 php-fpm 改成了 listen = 127.0.0.1:9000，nginx 就得对应 fastcgi_pass 127.0.0.1:9000;
• 路径或端口错一个字符，就 502 —— 而且 nginx error log 里通常只写“connect() failed”，不会告诉你具体连的是哪个路径

nginx location 块里 fastcgi_param SCRIPT_FILENAME 写错，PHP 报 No input file specified.

这个错误表面是 PHP 找不到文件，实际是 nginx 传过去的脚本路径不对。常见于 root 路径和 location 匹配不一致时。

比如站点根目录设在 /var/www/example.com，但 location 是 location ~ \.php$，而 fastcgi_param SCRIPT_FILENAME 写成 $document_root$fastcgi_script_name —— 看似合理，但一旦 $document_root 没配对，或者用了 alias，就会出问题。

稳妥写法是显式拼接，尤其当用 alias 时：

• 用 root：确保 root /var/www/example.com; 在 server 或 location 里已定义，然后 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
• 用 alias：不能依赖 $document_root，得写死路径，比如 fastcgi_param SCRIPT_FILENAME /var/www/example.com$fastcgi_script_name;
• 务必检查 $fastcgi_script_name 是否含 .php —— 它来自请求 URI，如果 rewrite 规则改了它，SCRIPT_FILENAME 就会指向错误位置

php-fpm pool 配置影响权限和超时，504 Gateway Timeout 往往卡在这儿

504 不是连不上，而是连上了但等太久。默认 php-fpm 的 request_terminate_timeout 和 nginx 的 fastcgi_read_timeout 都偏保守，尤其跑 Composer、大文件导出或调试模式时容易触发。

关键参数要两边对齐：

• php-fpm pool 配置（如 /etc/php/8.1/fpm/pool.d/www.conf）里：request_terminate_timeout = 300（单位秒），同时确保 pm.max_children 足够，否则并发一高就排队
• nginx 的 server 或 location 块里：fastcgi_read_timeout 300;（必须 ≥ php-fpm 的 timeout）
• 别漏掉 fastcgi_connect_timeout 和 fastcgi_send_timeout，上传大文件时它们也起作用
• 权限问题常被忽略：php-fpm worker 用户（如 www-data）必须对 .php 文件和 session.save_path 有读写权，否则可能静默失败

启用 opcache 后改代码不生效？不是 nginx 缓存，是 PHP 自己没重载配置

opcache 是 PHP 内部机制，和 nginx 无关。改了 PHP 代码却看不到效果，大概率是 opcache 缓存了字节码，而且默认不检查文件修改时间。

开发环境建议调低或关掉验证频率：

• 在 php.ini 或 opcache.ini 里设：opcache.validate_timestamps=1（默认就是 1，但某些发行版打包时会关）
• 再设：opcache.revalidate_freq=2（单位秒，表示每 2 秒检查一次文件改动）
• 改完配置必须重启 php-fpm，systemctl reload php-fpm 不一定生效，得 restart
• 线上环境别开 validate_timestamps，性能损耗明显；用部署工具清 opcache 或设版本号强制刷新更稳妥

真正难排查的，是多个 php-fpm pool 共存时，你改了 A pool 的配置，但 nginx 实际连的是 B pool —— 这时候看 fastcgi_pass 和 pool sock 文件名 是否真对应，比猜快得多。

理论要掌握，实操不能落！以上关于《Nginx配置PHP站点详细教程》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！