Ubuntu 上分析 PHP-FPM 错误日志的实用流程
一 定位日志文件与快速查看
- 常见日志路径
- PHP-FPM 进程日志：/var/log/php**{version}**-fpm.log 或 /var/log/php-fpm/error.log（按发行版与安装方式不同而异）。
- PHP 应用错误日志：由 php.ini 的 error_log 决定，常见有 /var/log/php_errors.log；若使用 Nginx，相关错误也可能落在 /var/log/nginx/error.log。
- 快速查看与跟踪
- 实时跟踪：sudo tail -f /var/log/php**{version}**-fpm.log
- 分页查看：less +F /var/log/php**{version}**-fpm.log
- 确认 PHP 错误日志路径与开关
- 命令行：php -r “echo ini_get(‘error_log’);”
- 在 php.ini 中确保：log_errors = On，error_log 指向有效路径；生产环境建议 display_errors = Off。
二 读懂日志关键信息
- 错误级别与含义
- Parse error：语法错误，脚本无法解析（需立即修复）。
- Fatal error：致命错误，脚本终止（如调用未定义函数）。
- Warning/Notice：非致命问题，但提示潜在缺陷或不当用法。
- 上下文线索
- 时间戳、进程/池名、脚本文件名与行号：用于快速定位问题代码。
- 请求信息：如 URI、响应状态（如 500），帮助判断是否为服务器级错误。
- 性能指标：如 响应时间、内存使用，用于发现性能瓶颈。
- 与 Web 服务器日志联动
- 当出现 502/504 等网关错误时，同时查看 Nginx/Apache 错误日志，核对 FastCGI 通信与上游状态。
三 常见错误模式与排查路径
- 502 Bad Gateway
- 可能原因：PHP-FPM 未启动/崩溃；Nginx/Apache 与 PHP-FPM 通信地址不匹配（如 listen = 127.0.0.1:9000 与 fastcgi_pass 不一致）。
- 排查：systemctl status php**{version}**-fpm；核对 listen 与 fastcgi_pass；必要时重启服务。
- 504 Gateway Timeout
- 可能原因：脚本执行超时；进程/资源不足。
- 排查：调整 request_terminate_timeout（或 php.ini 的 max_execution_time）；增加 pm.max_children；优化慢脚本。
- “Primary script unknown”
- 可能原因：Nginx 未正确传递脚本路径。
- 排查：确保 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name 且 root 路径正确。
- 进程池耗尽（pm.max_children reached）
- 可能原因：并发超过进程上限。
- 排查：适当提升 pm.max_children；优化应用与并发；必要时切换 pm 策略（static/dynamic）。
- 权限问题
- 可能原因：PHP-FPM 运行用户对代码目录无读/执行权限。
- 排查：chown -R www-data:www-data /path/to/app；chmod -R 755 /path/to/app；核对 listen.owner/group。
- 内存耗尽（Allowed memory exhausted）
- 可能原因：脚本内存超限。
- 排查：提升 php.ini 的 memory_limit；优化代码与查询。
四 配置与工具优化
- 调整日志级别与路径
- 在 /etc/php/{version}/fpm/pool.d/www.conf 中设置：
- php_admin_value[error_log] /var/log/php-fpm/custom_error.log
- php_admin_flag[log_errors] on
- error_reporting（如 E_ALL & E_DEPRECATED & E_STRICT）
- 修改后重启：sudo systemctl restart php**{version}**-fpm
- 开启慢日志定位性能瓶颈
- 在 pool 配置中启用：request_slowlog_timeout 与 slowlog，记录执行时间超过阈值的脚本栈，便于优化 SQL/外部调用。
- 语法校验与配置测试
- 修改配置后先执行：php-fpm -t（语法检查）；再重启服务，避免配置错误导致不可用。
- 日志轮转与容量控制
- 使用 logrotate 定期切割 PHP-FPM 日志，防止单个日志过大影响分析与磁盘空间。
- 动态确认与临时调试
- 确认 error_log：php -r “echo ini_get(‘error_log’);”
- 开发环境可临时开启 display_errors 辅助定位，生产环境务必关闭，仅记录日志。
五 高效排查命令清单
- 实时跟踪与检索
- 跟踪 FPM 日志：sudo tail -f /var/log/php**{version}**-fpm.log
- 检索致命错误：grep -i “Fatal” /var/log/php**{version}**-fpm.log
- 检索慢日志：grep -i “slow” /var/log/php**{version}**-fpm.log（开启慢日志后）
- 服务与配置
- 查看状态：systemctl status php**{version}**-fpm
- 语法检查：php-fpm -t
- 重启服务：sudo systemctl restart php**{version}**-fpm
- 权限与资源
- 修正权限：chown -R www-data:www-data /var/www/html；chmod -R 755 /var/www/html
- 资源检查：free -m（内存）、df -h（磁盘）
