doctor 找出原因。
doctor 按依赖顺序逐一检查 dev 会话的控制通道各环节——从磁盘上的就绪契约一直到对扩展内执行器的实时探测——并指出第一个失败的环节和具体修复方法,而不是让你面对每条命令各自的死胡同报错。
何时使用 doctor
extension logs或某个 act verb 连不上,你想知道是哪个环节断了。- agent 或脚本通过
ready.json驱动会话,需要一个机器可读的健康检查。 - dev 会话看起来还活着,但扩展不再响应。
用法
参数与 flag
doctor 如何选择会话
不带 --browser 时,doctor 诊断的是实际存在的会话,而不是某个写死的默认值。它会列出 dist/extension-js/ 下的就绪契约,并据此解析:
- 只有一个存活契约时,直接选它。
- 有多个契约时,存在
chromium就选chromium,否则按字母序选第一个。随后会有一个session-resolutionwarn 检查,在编号检查开始前列出所有候选。 - 完全没有契约时,
doctor回退到chromium。
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。没有退出证据并不等于浏览器还活着。
✓ 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 检查会失败,说明该命令正在没有控制通道的情况下运行,并给出带控制通道重启它的命令:
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 由第一个失败的检查决定:
典型流程
- 启动会话:
extension dev --browser=chromium --allow-control(需要 eval verb 时加--allow-eval)。 - 后续命令连不上时,在同一项目根目录运行
extension doctor。 - 按第一个失败检查给出的修复建议处理,然后再次运行
doctor确认。

