PHP fibers 如何安全交接阻塞任务：Fiber::suspend 与 resume 的生命周期排查

把阻塞任务交给 PHP Fiber 后，最容易踩的坑不是不会调用 Fiber::suspend()，而是忘了它每次恢复都对应一个明确状态。一个 Fiber 只能 start() 一次；暂停后用 resume() 交回值，终止后再通过 getReturn() 取结果。只要把这条生命周期线画清楚，重复恢复、提前取返回值和异常分支就很好定位。

Fiber 不是自动并发线程：调用方负责在 suspended 状态恢复它，并在 terminated 状态读取结果。

先看清 Fiber 的状态边界

PHP 手册把 Fiber 定义为可中断的完整调用栈。创建对象后它尚未启动；start() 进入回调，执行到 Fiber::suspend() 时把控制权返回给调用方。此时 isSuspended() 为真，只有再次 resume() 或 throw()，回调才会继续。

用最小脚本复现交接过程

下面的回调暂停一次，并把 resume() 传入的字符串接回来。这个示例故意保留调用顺序，方便在日志里对照状态变化。

start();
echo $first, PHP_EOL;

if ($fiber->isSuspended()) {
    $fiber->resume('订单-42');
}

if ($fiber->isTerminated()) {
    echo $fiber->getReturn(), PHP_EOL;
}
?>

第一次输出来自 start() 返回的暂停值“等待输入”。resume('订单-42') 之后，字符串从 Fiber::suspend() 表达式返回，回调执行到 return，最后 getReturn() 得到“收到：订单-42”。

线上排查先看哪个信号

遇到 FiberError 时，先打印三个状态，不要在 catch 里盲目再次 resume()。未启动的 Fiber 只能 start，已暂停的 Fiber 才能 resume，已终止的 Fiber 只能读取返回值。若回调抛出未捕获异常，getReturn() 也不会给出正常结果，应该保留原异常作为任务失败原因。

重复恢复为什么会失败

resume() 不是“推动一下”的无条件操作，它要求 Fiber 正处于 suspended 状态。恢复后如果回调直接返回，状态已经变成 terminated，下一次恢复自然越界。

Fiber 会不会自己并发运行

不会。Fiber 只提供可暂停的执行栈，调度循环、I/O 就绪通知和恢复时机仍由应用或异步框架负责。把它当成线程会导致忙等和错误的资源释放顺序。

上线前的回滚与复查

改造现有阻塞代码时，先保留原调用路径，用一个请求或一个队列任务接入 Fiber。日志至少记录任务标识、isSuspended()、isTerminated() 和异常类名。若新路径出现重复恢复，立即回退到原同步调用，并检查是否把同一个 Fiber 放进了两个调度队列。

常见问题

PHP Fiber 从哪个版本开始可用？

PHP 手册标注 Fibers 从 PHP 8.1.0 起提供。部署前应以目标运行环境的 PHP_VERSION 和官方手册为准。

Fiber::suspend() 返回什么？

它会在 Fiber 内接收下一次 resume() 传入的值；第一次暂停时，调用方拿到的是 suspend() 自己传出的值。

什么时候调用 getReturn()？

确认 isTerminated() 为真后再调用。Fiber 尚未结束，或以未捕获异常结束时，都不应把它当成正常返回读取。

把状态检查留在调度边界

Fiber 的难点集中在边界，不在语法。把 start()、resume()、getReturn() 分别绑定到未启动、已暂停、已终止三个状态，再为异常保留独立分支，调度代码就能做到可观察、可回退，也不会靠重复恢复“碰运气”。