PHP-FPM 在 Linux 中的错误排查步骤
一 快速定位与日志优先
- 查看服务状态与最近日志，确认是否为进程未启动或异常退出：
- 查看状态：systemctl status php7.x-fpm
- 实时看日志：journalctl -u php7.x-fpm -f
- 检查 PHP-FPM 自身错误日志，常见路径（按发行版与版本可能不同）：
- /var/log/php-fpm.log、/var/log/php7.x-fpm.log、/var/log/php-fpm/error.log
- 若未配置专用日志，可能写入系统日志：/var/log/syslog
- 若由 Nginx/Apache 代理，同时查看 Web 服务器错误日志：
- Nginx：/var/log/nginx/error.log
- Apache：/var/log/apache2/error.log（CentOS/RHEL 常为 /var/log/httpd/error_log）
- 无法判断日志位置时，可在 PHP 中临时输出 phpinfo()，查看 error_log 指令的实际路径。
二 配置语法与进程状态检查
- 测试配置语法，优先排除配置错误：
- 查看与清理进程冲突，避免“已在运行/端口占用”导致启动失败：
- 重启服务：systemctl restart php7.x-fpm
- 检查端口占用（FPM 常用 9000）：netstat -tulnp | grep 9000
- 核对主配置与进程池配置：
- 主配置：/etc/php/7.x/fpm/php-fpm.conf
- 进程池：/etc/php/7.x/fpm/pool.d/www.conf（重点核对 listen、用户组、日志路径等）
三 常见错误与对应处理
| 症状 |
高频原因 |
排查与修复要点 |
| 502 Bad Gateway |
PHP-FPM 未启动/崩溃；与 Nginx/Apache 通信失败 |
1) systemctl status php7.x-fpm 看是否运行 2) 核对 listen=127.0.0.1:9000 与 Nginx fastcgi_pass 一致 3) 查看 FPM 与 Web 日志定位失败点 |
| 504 Gateway Timeout |
脚本执行超时；FPM 进程/资源不足 |
1) 调整 FPM 的 request_terminate_timeout 2) 增加 pm.max_children 或优化脚本性能 3) 开启慢日志定位耗时脚本 |
| Primary script unknown |
Nginx 未正确传递脚本路径 |
在 Nginx 配置中确保有：fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; 且 root 路径正确 |
| Permission denied（unix socket） |
FPM 与 Web 服务器用户/权限不匹配 |
在 www.conf 中核对 listen.owner / listen.group / listen.mode，常见为 www-data:www-data，必要时设为 0660 或 0666 并重启 |
| Address already in use（端口冲突） |
9000 被其他进程占用 |
**netstat -tulnp |
| Unable to load dynamic library ‘xxx.so’ |
扩展未安装或路径错误 |
安装对应扩展（如 php7.x-mysql），或修正 extension= 路径 |
| Allowed memory exhausted |
脚本内存超限 |
提升 memory_limit，并优化代码减少内存占用 |
| 进程池耗尽 |
pm.max_children 过小或慢脚本阻塞 |
提升 pm.max_children，使用 request_slowlog_timeout 抓慢脚本并优化 |
| 日志文件不存在/无法写入 |
目录或文件权限不足 |
创建日志目录并赋权，例如：mkdir -p /var/log/php7.4-fpm && chown www-data:www-data /var/log/php7.4-fpm |
以上问题及处理要点可结合日志与配置快速验证与修复。
四 深入排查与优化建议
- 开启并利用慢日志定位性能瓶颈：
- 在 www.conf 设置：slowlog = /var/log/php-fpm/www-slow.log 与 request_slowlog_timeout = 5，对超过阈值的脚本记录堆栈与调用信息，针对性优化 SQL/外部请求/循环等。
- 调整进程模型与资源上限，避免并发高峰“雪崩”：
- 依据内存与负载选择 pm = dynamic/ondemand/static，并合理设置 pm.max_children、pm.start_servers、pm.min_spare_servers、pm.max_spare_servers；必要时设置 pm.max_requests 定期回收子进程，缓解第三方扩展内存泄漏风险。
- 调整 FPM 请求超时，避免长阻塞拖垮进程池：
- request_terminate_timeout 控制 FPM 层最大执行时间（不受 max_execution_time 完全限制）；对 file_get_contents 等流操作建议显式设置超时上下文，防止进程被长时间挂起。
- 权限与运行用户一致性：
- 确保 listen.owner / listen.group 与 Nginx/Apache 运行用户一致（如 www-data），目录与文件对 FPM 用户可读写；使用 chown/chmod 修正后重启 FPM。
- 日志轮转与容量控制：
- 配置 logrotate 对 php-fpm.log 进行按日/按大小切割，避免日志过大影响磁盘与排查效率。
五 一键排查清单
- 查看服务与实时日志：systemctl status php7.x-fpm && journalctl -u php7.x-fpm -f
- 检查 FPM 错误日志：tail -f /var/log/php-fpm.log /var/log/php7.x-fpm.log /var/log/php-fpm/error.log /var/log/syslog
- 语法与配置核对：php-fpm7.x -t；核对 /etc/php/7.x/fpm/php-fpm.conf 与 /etc/php/7.x/fpm/pool.d/www.conf
- 端口与进程：netstat -tulnp | grep 9000；必要时 systemctl restart php7.x-fpm
- Web 层日志：tail -f /var/log/nginx/error.log 或 /var/log/apache2/error.log（CentOS/RHEL 可能为 /var/log/httpd/error_log）
- 权限与目录：确认 /var/log/php7.x-fpm 存在且属 www-data，FPM listen 权限与 Nginx/Apache 一致
- 仍未解决：临时提升 log_level = debug 复现问题，结合慢日志与 strace 深入分析