dev、start 和 preview 会为每一次生命周期状态变化流式输出一个 schema-1 帧。每个帧本身就是独立成行的一个完整结果信封。
打开这个流
这个流由EXTENSION_OUTPUT 环境变量控制。把它设为 json 或 ndjson,帧就会独占 stdout:
帧的状态
每个帧的
value 都携带会话身份:command、browser、distPath、pid、port,以及已知时的 readyPath、eventsPath、runId、instanceId 和 toolchainVersion。
在会话开始之前就被拒绝的运行只发送一个 failed 帧,不会有 starting 帧。缺少 manifest、配置文件加载失败,以及远程 URL 没有可用的归档,都以这种方式结束。
编译失败
compile-failed 帧会把编译器输出放在 value.output 里,所以你永远不需要去刮 stdout。这段输出已经去掉 ANSI 控制符,并且上限为 2000 个字符。当上限把它截断时,该帧会设置 truncated: true。
一次会话中的第一次失败使用错误码 E_FIRST_COMPILE,之后每一次都使用 E_COMPILE。
该帧还会携带 error.details,每条诊断一个条目,各自带有错误码、文件和位置,错误排在前面,结构见结果信封中的”编译诊断”一节。列表上限为 20 条,当输出或列表任一被截断时,都会设置 truncated: true。
ready 遵循契约
ready 帧在触发之前会读取 ready.json。编译可能成功,而浏览器却拒绝了这个扩展,发生这种情况时契约会保持在 error。
这种情况下,流改为发出一个错误码为 E_READY_ERROR_STATUS 的 failed 帧,并由 value.readyCode 指出契约自身的错误码。
浏览器根本没有启动,或者在扩展加载之前就退出时,到达的也是同一个帧。这时 value.readyCode 是 browser_launch_failed 或 browser_exited。Firefox 的调试器始终没有应答时,按启动失败处理。
--chromium-binary 或 --gecko-binary 固定的二进制有问题时,readyCode 同样是 browser_launch_failed,但其帧带 status: "usage" 与 error.code: "E_BROWSER_BINARY_INVALID",这也是每个命令对这种固定路径给出的代码。
Chromium 的 dev 会话在浏览器起来之后 CDP 连线失败时,仍然会发送 ready,因为浏览器在运行。该帧会把故障放在 warnings 里,形式为 E_CDP_...: message,与契约盖上的 cdpFaultCode 和 cdpFaultMessage 是同一对值,见 ready.json。在故障修复前,reload 和 HMR 无法接上。
浏览器退出
一个后台监视器每秒轮询一次ready.json,查找启动器写下的退出戳记。当 browserExitedAt 出现时,流会发出一个 browser-exited 帧。
这个帧的错误码取决于契约里的证据:
E_PROFILE_LOCKED:契约显示配置文件被锁定。浏览器根本没有启动,另一个会话正占用该配置文件。E_BROWSER_LAUNCH:其余所有意外退出。
value 会携带 exitCode 和 browserExitedAt。
下一步
- 在 ready.json 中阅读这些帧背后的契约。
- 在 用 agent 驱动 CLI 中了解如何从 agent 驱动整个循环。

