跳轉到主要內容
當 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 session 上的拒絕。
  • 當契約沒有寫入 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。