PHP CLI 退出码为什么被吞掉：Throwable、register_shutdown_function 与日志验收

凌晨的定时任务日志里明明写着 RuntimeException: sync failed，CI 却把这一步标成绿色。继续查才发现，脚本在异常后又走了 register_shutdown_function()，最后一行输出看起来像收尾成功，调用方真正拿到的退出状态却没有被单独验收。PHP CLI 的报错内容和进程退出码是两条相关但不相同的信号。

要让 shell 和 CI 稳定识别失败，必须在异常边界明确写出非零退出码；shutdown 回调只负责记录最后状态，不应把失败改写成成功。

先复现“日志有错但任务成功”的现场

把下面脚本保存为 job.php，让它捕获一个明确的异常，再观察命令行的两种结果。第一种只打印错误；第二种在失败分支显式调用 exit(1)。

 true,
        'last_error' => $last,
    ], JSON_UNESCAPED_UNICODE) . PHP_EOL, FILE_APPEND);
});

try {
    throw new RuntimeException('sync failed');
} catch (Throwable $e) {
    fwrite(STDERR, $e::class . ': ' . $e->getMessage() . PHP_EOL);
    // 如果这里没有 exit(1)，脚本可能以 0 结束。
}

运行脚本后别只盯着终端输出的红字就下结论，一定要顺手查一下当前进程的退出状态：

php job.php
printf 'exit=%s\n' "$?"

在没有显式失败退出的版本里，常见现象是 stderr 有 sync failed，但 exit=0。这不是 PHP 把异常“吞了”，而是代码已经捕获它，并且没有把失败继续传给进程边界。

时间线里有三个不同的结束点

很多人碰到这类问题理不清逻辑，本质是大家习惯把“异常抛出”“日志落盘”“进程终止”这几件挨得很近的事当成同一个操作。实际排查的时候，我们可以把它们拆成三个独立的事件节点：

1. 业务事件：代码抛出或捕获 Throwable，决定是否还能继续当前任务。
2. 记录事件：日志处理器和 shutdown 回调写入运行上下文，但这两类逻辑本身不会自动修改进程的退出状态。
3. 进程事件：主脚本通过 exit(1) 或未捕获异常结束，shell 才能取得非零结果。

register_shutdown_function() 的回调会在脚本结束前运行。它可以把任务名、批次号和最后错误写下来，方便定位“进程为什么结束”；但如果回调里无条件输出“done”，就会制造一种危险的视觉错觉：日志像成功，退出状态却被别的路径决定。

为什么 shutdown 回调不能替代异常处理

shutdown 回调适合做“最后一眼”的记录，例如写入脚本名、主机名和批次号。它不适合作为主控制流，因为这时很多资源已经进入关闭阶段，而且 error_get_last() 只提供最后一条 PHP 错误数组，字段可能是 type、message、file、line，也可能是 null。

还要注意两种失败的差别。未捕获的 Throwable 通常会让 CLI 以非零状态结束；被 catch 后继续执行的异常则不会自动替你退出。至于内存耗尽、解析错误等致命场景，shutdown 回调可能有机会读取到最后错误，但不应假设所有错误都能被可靠补救。

function writeShutdownRecord(): void
{
    $last = error_get_last();
    $record = [
        'script' => basename($_SERVER['SCRIPT_NAME'] ?? 'unknown'),
        'last_error_type' => $last['type'] ?? null,
        'last_error_message' => $last['message'] ?? null,
    ];
    file_put_contents(
        __DIR__ . '/job-shutdown.log',
        json_encode($record, JSON_UNESCAPED_UNICODE) . PHP_EOL,
        FILE_APPEND | LOCK_EX
    );
}

register_shutdown_function('writeShutdownRecord');

这里的回调只做状态采集操作就好。真正的任务成功失败判定逻辑要放在主业务流程里，不能出现 shutdown 阶段日志写入成功，就直接把整个业务任务误标记为执行完成的情况。

把失败边界写成一个可复用入口

比起在每个 catch 里随手打印一行，CLI 任务更适合统一入口：正常返回 0，业务失败记录上下文后返回 1，参数或环境错误使用另一种非零状态。数字本身可以按团队约定，但同一项目必须保持一致。

getMessage()
        ));
        return 1;
    }
}

$code = runJob();
exit($code);

如果还需要在脚本收尾阶段登记 shutdown 相关记录，要先注册好回调函数，再调用业务入口方法。回调逻辑不需要自行猜测业务最终结果；可以把最终要返回的退出码放到引用传值的闭包变量里传递状态：

$exitCode = 1;
register_shutdown_function(function () use (&$exitCode): void {
    file_put_contents('job-shutdown.log', json_encode([
        'exit_code' => $exitCode,
        'last_error' => error_get_last(),
    ], JSON_UNESCAPED_UNICODE) . PHP_EOL, FILE_APPEND);
});

$exitCode = runJob();
exit($exitCode);

这样日志里的 exit_code 与 shell 的 $? 有了可比对的依据。若日志写入失败，也要让监控知道“证据缺失”，不要用一条格式漂亮的 done 日志覆盖主任务失败。

在 shell、CI 和定时任务里做反向验收

验收脚本至少要覆盖四部分校验：命令的 stdout 和 stderr 输出、进程退出状态、shutdown 阶段的记录、失败场景下是否能拿到可直接定位的异常类型信息。最基础的 shell 断言可以参照下面的写法：

set +e
php job.php >job.stdout 2>job.stderr
code=$?
set -e

test "$code" -ne 0
grep -q 'RuntimeException' job.stderr
grep -q '"exit_code":1' job-shutdown.log

CI 流水线配置里不要用“日志包含 failed 关键词”来替代对命令实际退出状态的判断；日志里的失败关键词可能来自旧任务重试、历史残留文件或者并行执行的其他步骤。线上定时任务也要把 stderr 输出和进程退出码一起上报到告警系统，方便后续区分是“业务脚本本身执行失败”还是“日志收集服务自身出现故障”。

常见问题

捕获了 Throwable 后，PHP 会自动返回非零吗？

不会。异常被捕获之后，程序可以继续向后走预设的正常路径；如果最终没有主动声明非零退出状态，外层 shell 很可能拿到 0 这个默认成功值。

register_shutdown_function() 能捕获所有错误吗？

不能。它可以尝试读取最后一次错误信息，但它不是全局的完整异常总线，也没法保证覆盖所有致命错误场景、留下完整的上下文信息。

直接在 catch 里写 exit(1) 可以吗？

小型单脚本可以直接用，但共享业务代码里不适合到处写退出逻辑。统一在入口层返回状态码，后续做单元测试会更方便，也能让调用方自己决定是否要执行重试策略。

让退出码成为任务契约的一部分

PHP CLI 的可靠性不只体现在错误有没有打印出来，还体现在调用方能否据此停止流水线、触发重试或发出告警。把 Throwable 的处理放在统一入口，用 shutdown 回调补充最后状态，再用 shell 断言验证 stderr、退出码和收尾记录，才能避免“日志看着失败，任务却显示成功”的灰色结果。