笙亿网络策划

如何设置 PHP-FPM 的 catch_workers_output 捕获标准输出错误？

约 6 分钟读完 2 阅
文章导读
在 PHP-FPM 的池配置文件（通常是 www.conf）中将 catch_workers_output 设置为 yes，即可将 worker 进程的标准输出和错误重定向到主错误日志。该设置适用于调试丢失的报错信息，但在高流量生产环境需谨慎开启以避免日志膨胀。
📋 目录
  1. A 命令速用版
  2. B 为什么会这样
  3. C 分步处理
  4. D 怎么验证是否生效
  5. E 常见坑
  6. F 常见问题
  7. G 参考来源
A A

在 PHP-FPM 的池配置文件（通常是 www.conf）中将 catch_workers_output 设置为 yes，即可将 worker 进程的标准输出和错误重定向到主错误日志。该设置适用于调试丢失的报错信息，但在高流量生产环境需谨慎开启以避免日志膨胀。

先说结论：开启 catch_workers_output 能捕获 worker 进程直接输出的内容，适合排查日志中缺失的警告或 echo 信息。

  • 适合：开发环境调试、排查空白页或日志不全问题
  • 先准备：确认 php-fpm 主日志路径 error_log 可写
  • 再验证：reload 配置后触发脚本，检查主日志是否有预期输出

命令速用版

如果熟悉命令行，可以通过以下步骤快速定位并修改配置。注意不同 Linux 发行版的配置文件路径可能不同。

# 1. 查找 php-fpm 池配置文件位置
find /etc -name "www.conf" 2>/dev/null

# 2. 修改配置，将 no 改为 yes（以 Ubuntu 为例）
sed -i 's/catch_workers_output = no/catch_workers_output = yes/' /etc/php/8.1/fpm/pool.d/www.conf

# 3. 平滑重载配置
systemctl reload php8.1-fpm

为什么会这样

PHP-FPM 的 worker 进程默认独立运行，其标准输出不会自动进入主日志。PHP-FPM 主进程与 worker 进程是分离的，worker 进程产生的 stdout 和 stderr 默认可能直接丢弃或发送到 Web 服务器日志，导致 php-fpm.log 中看不到某些 echo 或警告信息。开启该选项后，FPM 主进程会拦截这些输出并统一写入配置的 error_log 文件中，便于集中排查问题。

分步处理

按照以下顺序修改配置，确保每一步都有检查点，避免配置错误导致服务不可用。

步骤 1：确认配置文件路径
不同系统路径不同，常见路径如下：

  • Ubuntu/Debian: /etc/php/{版本}/fpm/pool.d/www.conf
  • CentOS/RHEL: /etc/php-fpm.d/www.conf
  • 源码编译：/usr/local/php/etc/php-fpm.d/www.conf 或 php-fpm.conf

如果不确定，查看 phpinfo() 中的 FPM 配置路径，或使用 find 命令查找。

步骤 2：修改 catch_workers_output 参数
使用文本编辑器打开池配置文件，搜索 catch_workers_output。如果该行被注释（前面有分号;），去掉分号并将值改为 yes。

catch_workers_output = yes

步骤 3：确认主日志路径
捕获的输出会写入 php-fpm 的主错误日志，而不是网站的 access.log。在 php-fpm.conf 主配置文件中确认 error_log 路径。

error_log = /var/log/php-fpm/error.log

确保该文件所在目录存在且 php-fpm 运行用户有写入权限。

如何设置 PHP-FPM 的 catch_workers_output 捕获标准输出错误？

步骤 4：重载服务
修改完成后不要 restart，使用 reload 平滑重载配置，避免中断正在处理的请求。

systemctl reload php-fpm

怎么验证是否生效

配置修改后，需要通过实际输出来验证日志是否捕获成功。

验证动作：创建一个测试 PHP 文件，内容包含 echo 和 trigger_error。

<?php
echo "Test Output";
trigger_error("Test Error", E_USER_WARNING);
?>

检查日志：在终端使用 tail 命令实时监控 FPM 主日志文件。

tail -f /var/log/php-fpm/error.log

判断结果：访问测试页面后，如果日志中出现 "Test Output" 或相关警告信息，说明配置生效。如果日志无变化，检查 Web 服务器（Nginx/Apache）是否拦截了输出，或确认修改的是正在运行的 PHP 版本配置文件。

常见坑

  • 日志膨胀风险：生产环境如果代码中有大量 echo 或 debug 输出，开启此项会导致日志文件迅速增大，占用磁盘空间。
  • 配置层级混淆：该参数属于池配置（pool config），通常在 www.conf 中修改，而不是 php.ini 或 php-fpm.conf 主文件。
  • 权限问题：如果 error_log 指定的路径权限不足，FPM 可能启动失败或无法写入捕获的内容。
  • 多版本共存：服务器同时运行多个 PHP 版本时，确保修改的是当前网站实际使用的 PHP-FPM 版本配置。

常见问题

开启后会影响性能吗？

对 CPU 计算性能影响极小，但会增加日志 I/O 写入量。在高并发场景下，频繁的日志写入可能成为瓶颈，建议仅在调试时开启。

能捕获 PHP 脚本的 echo 输出吗？

能，开启后 worker 进程的标准输出（包括 echo、print）会被重定向到 FPM 错误日志中。

为什么修改后日志还是空的？

检查是否修改了正确的 php-fpm 配置文件，确认是否执行了 reload 操作，并核实 error_log 路径是否有写入权限。

参考来源

  • PHP Official Documentation - FPM Configuration: https://www.php.net/manual/en/install.fpm.configuration.php
  • PHP Source Code - php-fpm.conf.default: https://github.com/php/php-src/blob/master/sapi/fpm/php-fpm.conf.in