PHP-FPM 在 Linux 中的错误处理与排查指南
一 快速定位与通用排查
- 查看服务状态与启动日志：使用 systemctl status php-fpm 观察是否 active、是否反复重启；必要时用 journalctl -xeu php-fpm 查看详细系统日志。
- 测试配置语法：执行 php-fpm -t，定位配置文件语法或包含文件错误。
- 核对监听地址与端口：确认 /etc/php//fpm/pool.d/www.conf 中的 listen（如 127.0.0.1:9000 或 /run/php/php-fpm.sock）与 Nginx/Apache 一致。
- 检查端口占用：使用 ss -tulnp | grep 9000 或 netstat -tulnp | grep 9000 排查端口冲突。
- 查看错误日志：FPM 错误通常写入 /var/log/php-fpm.log 或 /var/log/php-fpm.log；若配置了 syslog，也可能在 /var/log/syslog。
- 重启并观察：修改后执行 systemctl restart php-fpm，再次查看状态与日志确认恢复。
二 常见错误与修复对照表
| 症状 |
可能原因 |
快速修复 |
| 502 Bad Gateway |
FPM 未启动、崩溃或与 Web 服务器通信失败 |
检查 systemctl status 与 journalctl；确认 listen 与 Nginx fastcgi_pass 一致；重启 FPM |
| 504 Gateway Timeout |
脚本执行超时、进程/资源不足 |
调整 request_terminate_timeout（FPM）与 pm.max_children（进程池）；优化慢脚本 |
| Primary script unknown |
Nginx 未正确传递脚本路径 |
在 Nginx 配置中加入：fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; 并核对 root 路径 |
| Permission denied（unix socket） |
Socket 文件权限/属主不匹配 |
在 www.conf 设置 listen.owner=www-data、listen.group=www-data、listen.mode=0666；重启 FPM |
| Address already in use（端口 9000） |
端口被占用 |
改用其他端口或终止占用进程；同步修改 FPM 与 Web 服务器配置 |
| 进程池耗尽（pm.max_children reached） |
并发超限 |
提升 pm.max_children 或优化应用与数据库；考虑切换 pm=dynamic/ondemand |
| Allowed memory exhausted |
脚本内存超限 |
提升 memory_limit（php.ini）；优化代码与查询 |
| 空白页或语法错误 |
错误未显示、脚本语法错误 |
临时开启 display_errors=On；用 php -l script.php 检查语法；查看 FPM/PHP 错误日志 |
三 日志与错误输出配置
- FPM 自身日志：在 php-fpm.conf 或 pool.d/www.conf 设置 error_log = /var/log/php-fpm.log 与 log_level = notice/debug，便于定位启动与运行期问题。
- PHP 错误日志：在 php.ini 开启 log_errors = On、设置 error_log = /var/log/php_errors.log，并确保运行用户对日志文件与目录可写。
- 捕获 Worker 输出：在 www.conf 设置 catch_workers_output = yes，使 PHP 的错误与警告输出到 FPM 日志（便于排查“白屏/无日志”）。
- 避免覆盖：若使用 php_admin_value[error_log]，会覆盖 php.ini 的 error_log；用 phpinfo() 确认最终生效的日志路径与权限。
- 目录与权限：确保日志目录存在且属主正确，例如 /var/log/php-fpm 归属 www-data:www-data。
四 权限与进程管理要点
- 运行用户与目录权限：FPM 通常以 www-data 运行，确保网站目录（如 /var/www）与日志目录对 www-data 可读写；必要时执行 chown -R www-data:www-data /var/www。
- Socket 权限：若使用 unix socket，核对 listen.owner/group/mode，否则可能出现 Permission denied。
- 优雅重启与平滑升级：使用 kill -USR2 触发 FPM 重新加载配置与子进程，避免中断现有请求。
- 资源与稳定性：结合内存与 CPU 调整 pm.max_children、pm.start_servers、pm.min_spare_servers、pm.max_spare_servers；开启 request_slowlog_timeout 记录慢脚本定位瓶颈。
五 实战命令清单
- 服务与日志：
- 查看状态：systemctl status php7.4-fpm
- 查看日志：journalctl -xeu php7.4-fpm
- 配置与监听：
- 语法测试：php-fpm7.4 -t
- 端口占用：ss -tulnp | grep 9000
- 进程检查：ps aux | grep php-fpm
- 运行时诊断：
- 跟踪进程：strace -f -ff -t -d -p $(pidof php7.4-fpm)（定位异常退出/阻塞）
- 配置热加载：
- 平滑重启：kill -USR2 $(cat /run/php/php7.4-fpm.pid)
- Web 服务联动：
- Nginx 重载：systemctl reload nginx（在确认 FPM 恢复后执行）