跳转到主要内容
当一个 dev 会话(或与它通信的自动化 verb)不工作时,用 doctor 找出原因。 doctor 按依赖顺序逐一检查 dev 会话的控制通道各环节——从磁盘上的就绪契约一直到对扩展内执行器的实时探测——并指出第一个失败的环节和具体修复方法,而不是让你面对每条命令各自的死胡同报错。

何时使用 doctor

  • extension logs 或某个 act verb 连不上,你想知道是哪个环节断了。
  • agent 或脚本通过 ready.json 驱动会话,需要一个机器可读的健康检查。
  • dev 会话看起来还活着,但扩展不再响应。

用法

省略路径时,Extension.js 诊断当前工作目录对应的会话。

参数与 flag

doctor 如何选择会话

不带 --browser 时,doctor 诊断的是实际存在的会话,而不是某个写死的默认值。它会列出 dist/extension-js/ 下的就绪契约,并据此解析:
  • 只有一个存活契约时,直接选它。
  • 有多个契约时,存在 chromium 就选 chromium,否则按字母序选第一个。随后会有一个 session-resolution warn 检查,在编号检查开始前列出所有候选。
  • 完全没有契约时,doctor 回退到 chromium。
从 4.1.39 之后的版本起,仍在运行的会话优先于已经结束的会话。契约里写着 status: "stopped",或者它的进程已经不在,都算会话已经结束。一个会话在运行而其余都已结束时,doctor 诊断正在运行的那个。所有会话都已结束时,doctor 按同样的规则诊断其中一个,session-resolution 检查会如实说明:
对于已停止的会话,ready-contract 检查随后会失败,它的修复建议会写出重新启动该会话的命令。从 4.1.41 之后的版本开始,如果该会话因加载被拒而结束,这项检查会指出这次拒绝,doctor 会回答 E_EXTENSION_LOAD_REFUSED。

检查内容

检查按依赖顺序运行。当某个环节失败时,依赖它的后续检查会标记为 skip,并注明是被哪个检查阻塞的——skip 不等于通过。 只有当存在多个存活会话时,才会出现第零个 session-resolution 检查。它会给出 warn,并指明本次运行诊断的是哪个会话。从 4.1.39 之后的版本起,存在多个会话而且全部已经结束时,它也会出现。 在编号检查之前还有两个检查。当会话运行的是 chromium-emulator 目标时,engine 会失败,因为 doctor 无法诊断它。peer-rspack 只需要项目本身,所以无论有没有 dev 会话都会运行。当某个直接依赖声明的 @rspack/core peer 范围不包含 Extension.js 自带的版本时,它会失败。这种不匹配正是 npm install 以 ERESOLVE 失败的原因,修复建议会指出要执行的升级。 有些环节故意给出较宽松的结论:
  • 当端口文件还不存在时,port-agreement 通过。这个项目和浏览器的第一个会话没有任何可冲突的对象。
  • 在一次新编译后的 10 秒内,executor 报告 warn 而不是失败。service worker 可能还在附加中。请等到 ready.json 里出现 runtime: "attached" 再动作。
  • 从 4.1.41 之后的版本开始,如果构建里没有浏览器会运行的 background,executor 会立刻失败。这一行带的是 eval 打印的同一句话。见 start 或 preview 会话上的拒绝。
  • 当契约没有写入 cdpPort,也没有记录退出时,browser 报告 skip。没有退出证据并不等于浏览器还活着。
pretty 输出每个检查打印一行,并附上第一个失败检查的修复建议。每种状态都有一个字形:✓ pass、✗ fail、! warn、– skip。全部通过时退出码为 0,任一检查失败时为 1,CI 和脚本可以直接据此把关。

来自 start 和 preview 的会话

从 4.1.39 之后的版本起,doctor 也会诊断带控制通道的 extension start 或 extension preview 会话,也就是用 --allow-control 或 --allow-eval 启动的会话。各行会点名那个命令,而不是 dev 服务器。 这样的会话不运行 dev 服务器,也不持久化控制端口,所以 port-agreement 不适用。这一行打印为 skip,不计入通过数,标题行会说明这一点:
在 --output json 下,这一行带有 "applicable": false:
一个让浏览器保持打开、却没有控制通道的 start 或 preview 运行,没有任何东西可供 doctor 连接。ready-contract 检查会失败,说明该命令正在没有控制通道的情况下运行,并给出带控制通道重启它的命令:
在 Firefox 上,Chromium 会话说 service worker 的那些行说的是 background page,因为 Firefox 把 background 当作一个页面来运行。

机器可读输出

--output json 打印一个 schema-1 信封。两种结论下检查结果都放在 value 里,因为不健康的报告也依然是报告:
健康的运行会返回 ok: true,并带上 status: "healthy" 和 error: null。 从 4.1.41 之后的版本开始,发现加载被拒的运行会保持 status: "unhealthy",并带上 error.code: "E_EXTENSION_LOAD_REFUSED"。见 Manifest 拒绝。 每个检查的 status 为 pass、fail、warn 或 skip。有已知修复方法的失败会带 remediation。信封的 error.code 由第一个失败的检查决定:

典型流程

  1. 启动会话:extension dev --browser=chromium --allow-control(需要 eval verb 时加 --allow-eval)。
  2. 后续命令连不上时,在同一项目根目录运行 extension doctor。
  3. 按第一个失败检查给出的修复建议处理,然后再次运行 doctor 确认。

下一步

  • 在 dev 中了解 doctor 的起点——就绪契约。
  • 通过 调试 从健康的会话中流式读取扩展日志。
  • 在 全局 flag 中查看共享 flag。