Skip to main content
当一个 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。

​
检查内容

检查按依赖顺序运行。当某个环节失败时，依赖它的后续检查会标记为 skip，并注明是被哪个检查阻塞的——skip 不等于通过。 只有当存在多个存活会话时，才会出现第零个 session-resolution 检查。它会给出 warn，并指明本次运行诊断的是哪个会话。 有些环节故意给出较宽松的结论：
  • 当端口文件还不存在时，port-agreement 通过。这个项目和浏览器的第一个会话没有任何可冲突的对象。
  • 在一次新编译后的 10 秒内，executor 报告 warn 而不是失败。service worker 可能还在附加中。请等到 ready.json 里出现 runtime: "attached" 再动作。
  • 当契约没有写入 cdpPort，也没有记录退出时，browser 报告 skip。没有退出证据并不等于浏览器还活着。
pretty 输出每个检查打印一行，并附上第一个失败检查的修复建议。每种状态都有一个字形：✓ pass、✗ fail、! warn、– skip。全部通过时退出码为 0，任一检查失败时为 1，CI 和脚本可以直接据此把关。

​
机器可读输出

--output json 打印一个 schema-1 信封。两种结论下检查结果都放在 value 里，因为不健康的报告也依然是报告：
健康的运行会返回 ok: true，并带上 status: "healthy" 和 error: null。 每个检查的 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。