Skip to main content
以每次状态变化一个 JSON 帧的方式跟随一个正在运行的会话。 一个终止信封无法描述一整个会话,因此 dev、start 和 preview 会为每一次生命周期状态变化流式输出一个 schema-1 帧。每个帧本身就是独立成行的一个完整结果信封。

打开这个流

这个流由 EXTENSION_OUTPUT 环境变量控制。把它设为 json 或 ndjson,帧就会独占 stdout:
流开启期间,原本共用 stdout 的人类可读文案会移到 stderr。错误文案始终留在 stderr,机器模式绝不会隐藏失败。

帧的状态

每个帧的 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。

下一步