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。
檢查內容
檢查依相依順序執行。某個環節失敗時,依賴它的後續檢查會標成 skip,並註明被哪個檢查擋住——skip 不等於通過。 只有存在多個存活工作階段時,才會出現第零個session-resolution 檢查。它會給出 warn,並指明這次執行診斷的是哪個工作階段。
有些環節刻意給出較寬鬆的結論:
- 當連接埠檔案尚未存在時,
port-agreement通過。這個專案與瀏覽器的第一個工作階段沒有任何可牴觸的對象。 - 在一次全新編譯後的 10 秒內,
executor回報 warn 而不是失敗。service worker 可能仍在附加中。請等到ready.json出現runtime: "attached"再動作。 - 當契約沒有寫入
cdpPort,也沒有記錄結束時,browser回報 skip。沒有結束的證據並不代表瀏覽器還活著。
✓ 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 由第一個失敗的檢查對應而來:
典型流程
- 啟動工作階段:
extension dev --browser=chromium --allow-control(需要 eval verb 時加上--allow-eval)。 - 後續指令連不上時,在同一個專案根目錄執行
extension doctor。 - 依第一個失敗檢查給的修復建議處理,然後再次執行
doctor確認。