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 session 上的拒絕。 - 當契約沒有寫入
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確認。

