pcntl_signal 清理怎么配置或排查

我给 PHP CLI worker 加优雅退出时，最容易误判的一点是：pcntl_signal() 只负责安装或替换处理器，并不会替你执行清理。可靠的做法是让 handler 设置一个停止标志，主循环看到标志后退出，再由 finally 统一关闭连接、文件和临时资源。

PHP 7.1 及以上优先开启 pcntl_async_signals(true)；如果运行环境较旧，就在循环中调用 pcntl_signal_dispatch()。不要把复杂清理直接塞进信号回调，否则很容易遇到重复释放、阻塞函数被打断或退出路径不完整。

先确认 pcntl_signal 能运行的前提

这类问题通常不是函数名写错，而是脚本根本没有 PCNTL 能力。官方手册说明，PCNTL 默认不启用，需要在编译 PHP CLI/CGI 时打开 --enable-pcntl；当前模块也不支持 Windows。生产 worker 先把环境检查做成启动失败，而不是等收到信号后才发现函数不存在。

上面的示例用于检查思路，实际注册 handler 时不要先把处理器设成默认值。更稳妥的启动检查是分别判断 PHP_SAPI、函数存在和目标常量存在；如果要主动给自己发信号，posix_kill() 还需要 POSIX 扩展。

PHP 版本变化决定信号怎样分发

我维护过一段从旧 PHP 升级到 7.1+ 的 worker，表面上只是删掉 declare(ticks=1)，实际变化是分发策略。pcntl_signal() 安装的是处理器，信号仍要通过异步分发或手动分发进入 PHP 回调。PHP 手册把异步分发列为推荐方式；PHP 7.1 起回调还可能收到第二个 siginfo 参数。

handler 只记下停止意图，别在回调里做重清理

pcntl_signal() 不会叠加同一信号的多个处理器，后一次注册会替换前一次。回调里直接关闭数据库、刷日志或等待子进程，看起来省事，实际上会让退出路径被打断。我的经验是只设置 $stopRequested，必要时记录信号编号；真正的资源操作留给正常的 PHP 控制流。

第三个参数 restart_syscalls 默认是 true，除非你明确知道系统调用被中断后的语义，否则不要为了“更快退出”随意改成 false。异步处理开启后，sleep() 等阻塞函数也可能提前返回，所以循环不能把一次 sleep 返回当成完整的业务周期。

把资源清理放在 finally，并验证只执行一次

清理逻辑的关键不是“收到信号立刻关”，而是无论正常完成、收到退出信号还是业务异常，都走同一个收尾点。下面的结构适合连接池、文件句柄和临时目录等资源；close() 自身也应设计成可重复调用。

runBatch();

        // 旧 PHP 使用手动分发时，每轮显式派发一次待处理信号。
        if (!empty($manualDispatch)) {
            pcntl_signal_dispatch();
        }
    }
} finally {
    // 幂等保护避免异常处理和退出处理同时关闭同一资源。
    if (!$cleaned) {
        $cleaned = true;
        $worker->close();
    }
}

图中的“停止标志”和“finally 清理”是两个不同边界：前者是信号层与业务层之间的最小协议，后者才是资源生命周期的终点。这样即使信号在批处理期间到达，当前批次完成后也能稳定落到同一处。

常见问题：为什么注册了却不清理

为什么 pcntl_signal() 返回成功但 handler 没执行？

先看是否启用了异步分发；旧环境是否每轮调用了 pcntl_signal_dispatch()；再确认信号发给的是 worker 的真实 PID，而不是父进程或已经退出的进程。

为什么清理代码执行两次？

常见原因是 SIGTERM 和业务异常各自调用了一套 close 逻辑。把关闭动作集中到 finally，再用一次性标志或让资源对象的 close() 幂等即可。

为什么加了异步信号后 sleep 时间不准？

信号处理可能打断阻塞调用。需要固定周期时，用绝对截止时间重新计算剩余等待时间，不要直接假设每次 sleep() 都完整等待了指定秒数。

迁移检查可以压缩成四项：确认 Unix CLI 和 PCNTL、选择异步或手动分发、handler 只改状态、所有资源从 finally 统一收尾。按这个顺序排查，通常比反复替换信号常量更快找到问题。