Swoole信号处理错误汇总及解决技巧

Swoole中的信号处理是一个深陷操作系统、Swoole运行时、PHP生命周期与协程调度四层交界处的复杂问题：pcntl_signal在协程中完全失效并非Bug，而是因Swoole接管信号调度并默认屏蔽；正确做法是在onWorkerStart中启用pcntl_async_signals(true)并配合pcntl_signal_dispatch()轮询，或优先使用协程安全的swoole_signal——但必须在主线程、事件循环前注册，禁用默认终止行为，并妥善处理连接清理时序，否则不仅收不到SIGTERM，还会引发大量“Connection reset by peer”和SWOOLE_ERROR_UNREGISTERED_SIGNAL等错误；真正可靠的信号处理，是环环相扣的系统工程，漏掉任一环节，信号就会静默消失或在日志里反复报错。

协程里pcntl_signal为什么完全不生效？

因为协程运行时（如 Swoole）接管了信号调度，主线程未显式注册监听，操作系统发来的信号会被内核丢弃或由非预期线程接收。你在onWorkerStart里调用pcntl_signal(SIGTERM, $callback)，大概率不会触发——Swoole 默认屏蔽了大部分信号，且协程调度器不转发信号到 PHP 用户层。

• 必须在onWorkerStart中、任何协程启动前调用pcntl_signal_dispatch()并启用信号分发：pcntl_async_signals(true)
• 仅支持SIGUSR1、SIGUSR2、SIGTERM、SIGINT等少数信号；SIGHUP在 Swoole 中默认被用于重载配置，不要覆盖
• PHP 7.4+ 必须配合pcntl_signal_dispatch()轮询，不能依赖“自动触发”——协程环境没有传统信号中断上下文
• 若使用Swoole\Coroutine（如Co\Http\Server），pcntl_signal基本失效，应改用swoole_signal函数

swoole_signal注册后仍收不到SIGTERM？检查这三点

swoole_signal是 Swoole 提供的协程安全信号接口，但它有硬性前提：只在主线程（Manager 进程或 Worker 进程的主循环线程）中有效，且必须在进程进入事件循环前注册。

• 注册位置错误：在onRequest或任意协程中调用swoole_signal → 无效，信号不会被监听
• 未关闭系统默认行为：Linux 下SIGTERM默认终止进程，需先调用swoole_signal(SIGTERM, $callback, false)的第三个参数设为false禁用默认终止
• Worker 进程未启用信号：确认$server->set(['enable_reuse_port' => true])等配置未干扰信号机制；某些 Docker 容器中init进程会劫持SIGTERM，需用tini作为 PID 1

Connection reset by peer和信号处理有关联吗？

表面无关，但深层耦合：当服务收到SIGTERM后开始优雅退出，若此时仍有未完成的 HTTP 请求或 WebSocket 连接，close动作可能触发对端 RST；反过来，大量Connection reset by peer日志若集中在进程退出前后，说明信号处理逻辑没做好连接清理时序。

• 不要在信号回调里直接$server->shutdown()——它会立即断开所有连接，引发批量 RST
• 正确做法是设标志位 + 主动等待：$isShuttingDown = true，然后在onRequest中拒绝新请求，在定时器中逐个close空闲连接
• 务必配合$server->exist($fd)检查连接状态再push或send，否则即使信号已处理，残留协程仍可能向已关闭 fd 写入，报错SWOOLE_ERROR_SESSION_CLOSED或Connection reset by peer

为什么SWOOLE_ERROR_UNREGISTERED_SIGNAL（707）总在日志里出现？

这个错误码表示 Swoole 底层尝试投递一个你没用swoole_signal注册过的信号，常见于第三方库（如某些 Redis 封装、自定义扩展）内部调用了kill()或raise()，但未与 Swoole 信号管理对齐。

• 不是你的代码直接写的信号，而是依赖的 C 扩展或子进程触发的 —— 比如用proc_open启动子进程后，子进程崩溃触发SIGCHLD，而你没注册它
• 解决方案不是“注册所有信号”，而是忽略非关键信号：swoole_signal(SIGCHLD, function() {})即可压制该错误，避免日志刷屏
• 若使用SWOOLE_BASE模式（非 Reactor 模式），部分信号无法被swoole_signal捕获，此时应改用pcntl_signal + pcntl_signal_dispatch轮询

信号处理在 Swoole 里从来不是“注册一下就完事”的事，它卡在 OS 层、Swoole 运行时、PHP 生命周期、协程调度四层交界处——漏掉任一环节，信号就静默消失，或者以错误码形式在日志里反复闪现。

理论要掌握，实操不能落！以上关于《Swoole信号处理错误汇总及解决技巧》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！