跳轉到主要內容
瀏覽器擴充功能難以除錯,是因為關鍵狀態藏在你不容易觸及的位置:會閒置的 MV3 service worker、隔離的 content script world、一失焦就關閉的 popup。Extension.js 在你執行中的開發 session 開啟一條小型的本機控制通道,讓你(或 AI agent、或 CI job)能直接觸及這些 context — 讀取它們記錄的內容、檢視它們渲染的結果、呼叫進去,並觸發使用者會觸發的事件。 它在本機運作、不需要帳號,觀察永遠免費。任何會 改變 狀態的操作則需要在每個 session 中明確啟用。

開啟方式

啟動帶有你所需控制旗標的開發 session:
以下每個操作都會作用在該 session,並以相同的方式指定 context,無論是讀取或執行動作。

你可以做什麼

extension logs 與 extension inspect 各自有專屬的參考頁面:logs 與 inspect。

共用旗標

每個會執行動作的指令都接受同樣這三個旗標:
  • --browser 選擇要作用的 session(預設 chromium)。
  • --timeout <ms> 限制一次往返的時間(預設 5000)。
  • --output <pretty|json> 選擇 stdout 的輸出形式。
當 session 缺少所需的解鎖旗標時,拒絕訊息會直接指出要用哪個旗標重新啟動:eval 對應 --allow-eval,其餘一律是 --allow-control。你不必猜自己漏掉了哪個限制。

哪些內容會寫到磁碟

除了即時通道之外,session 還會在 dist/extension-js/<browser>/ 下寫入只追加的紀錄:logs.ndjson 保存每一筆擷取到的日誌事件,actions.ndjson(在 session 帶有 --allow-control 時寫入)稽核執行過的控制動作。兩者在 session 結束後仍可讀取。 日誌合約也保留了結構化的 dx.signal 項目,那是關於執行階段自身健康狀況的機器可讀診斷資訊,過濾方式為 extension logs --signals-only。目前尚未有任何發送端,因此這個過濾器現在不會回傳任何內容。它的結構先行記錄下來,讓消費端在第一筆 signal 出現的那天就能據此分支。

指定 context

讀取與執行動作共用同一套詞彙 — 你指定介面名稱,Extension.js 會在它正在追蹤的 session 中解析出來。

範例:我的擴充功能真的改動了頁面嗎?

這個範例可以直接在預設樣板上執行。--context page 會在目前分頁的 MAIN world 中執行運算式,因此你可以檢查 content script 究竟對頁面做了什麼:
預設輸出就是值本身:字串直接輸出,其他型別則輸出為縮排的 JSON。當腳本需要讀取結果時加上 --output json,你會得到完整的信封:
你的運算式所觸發的任何 console.log,同時會經由 extension logs 流出,並以序號相互關聯 — 因此你能同時看到回傳值 以及 副作用。 若要呼叫 background,請以 Firefox 或 MV2 session 為目標,那裡的 background 是一個可以正常執行運算式的頁面:
在 Chromium MV3 上(預設樣板為 Chrome 建置的就是這種),background 是 service worker,而 Chrome 的擴充功能 CSP 會在那裡封鎖 eval。在這類建置上,--context background 回傳的是說明性的錯誤而非值。在 Chromium MV3 上請改用 --context page 或 --context content。extension.dev 的 MCP 伺服器在 Chromium MV3 session 上對其 eval 工具套用同樣的預設值。

session 已經結束時

從 4.1.39 之後的版本起,act 指令或 logs --follow 在連線之前,會先確認所選瀏覽器的 session 仍在執行。session 結束後,ready.json 檔案仍然留在磁碟上,所以單憑這個檔案並不能證明有 session 在執行。你用 Ctrl+C 停止了 session(檔案裡會留下 status: "stopped"),或者它的行程已經不在、控制埠也沒有回應,都算 session 已經結束。 這時指令會以結束碼 1 和 E_SESSION_NOT_FOUND 結束。訊息會說明 session 已經結束,給出原因,並印出重新啟動它的指令。這個指令是 extension dev、extension start 或 extension preview,取決於當初是哪一個啟動了 session:
印出來的指令帶著該指令所需的旗標:eval 是 --allow-eval,其他 act 指令是 --allow-control,logs --follow 則不帶旗標。 如果同一個專案裡另一個瀏覽器的 session 正在執行,訊息結尾會帶一則提示:
只有那個瀏覽器的 session 沒有被停止,而且它的控制埠有回應時,這則提示才會出現。已結束的 session 留下的 ready.json 不會觸發它。某個瀏覽器根本沒有 ready.json 時,拒絕訊息後面也會跟著同樣的提示。

start 或 preview session 上的拒絕

從 4.1.39 之後的版本起,由 extension start 或 extension preview 帶 --allow-control 或 --allow-eval 開啟的 session,會在每一則拒絕訊息裡寫出它自己的指令。dev session 說 restart the dev session 的地方,這類 session 說的是 restart the extension start session 或 restart the extension preview session。例如,在沒有 --allow-eval 的 preview session 上執行 eval,得到的回答是:
沒有 background 腳本或 service worker 的建置無法被控制,因為控制通道是從 background 連出來的。session 在啟動時會給出警告,同一則警告接下來還會寫出瀏覽器載入的資料夾:
此後每一個 act 指令都會以 E_CONTROL_UNAVAILABLE 失敗,並說明這個建置沒有 background:

跨瀏覽器支援

Extension.js 透過瀏覽器內的伴隨程式進行除錯,而非 Chrome DevTools Protocol,因此核心流程能觸及你自己的介面,在 Chrome 與 Firefox 上都可運作 — 過去「Firefox 用 RDP,不支援」的那堵牆,對這些工具而言已經不存在。 (在 Chromium MV3 建置上,eval --context background 回傳的是說明性的錯誤。MV3 的 background 是 service worker,而 Chrome 的擴充功能 CSP 在每個 MV3 建置上都會拒絕 unsafe-eval,不只是正式環境。在 Chromium MV3 上請在 page / content 中執行運算式,或改以 Firefox/MV2 建置為目標呼叫 background。)

日誌在瀏覽器裡的位置

extension logs 會把每個 context 合併成終端機上的單一時間軸(參見 logs)。當你想改看某個 context 在瀏覽器本身的主控台時,每個 context 都藏在不同的門後: 三個能省時間的細節:
  • 在 Chrome 上,service worker 連結也會喚醒閒置的 MV3 worker,所以 background 看起來像死掉時就用它。
  • Content script 的日誌永遠不會出現在擴充功能自己的檢查器。在頁面 DevTools 的主控台中,context 下拉選單可以過濾到你的擴充功能的 isolated world。
  • 在 Firefox 上,about:debugging 的 toolbox 涵蓋 background 與擴充功能頁面。Content script 的輸出留在頁面的 DevTools。
以上一切也都會流入 extension logs,依 context 標記,完全不用點開那些門。

安全性

這些限制有其用意,並非繁文縟節:
  • 在你自己的機器上,觀察不需要任何權限。 讀取日誌與 DOM 隨時可用。從另一台機器連線的用戶端必須出示 session 權杖。
  • 有界限的操作需要 --allow-control。 storage、reload 與 open 會改變狀態,因此你必須在每個 session 中明確啟用。
  • eval 需要 --allow-eval 以及 每個 session 的權杖。 權杖會寫入 dist/ 外的 0600 檔案,因此絕不會包含在建置產物中 — 隨機的本機程序無法悄悄操控你的 service worker。
  • 網頁無法連線。 控制 socket 會拒絕帶有網頁來源(http://、https:// 或 null)的交握,因此瀏覽器中開啟的網站無法連到它。
  • 絕不會進入正式環境。 控制通道只在 dev/preview 期間存在,且綁定在已建置產物中不存在的連接埠上。

工作階段在瀏覽器裡觸及什麼

開發瀏覽器會開啟一個僅供 Extension.js 程序使用的遠端偵錯連接埠。工作階段透過它只附加到你擴充功能自己的目標:背景 worker,以及在 --logs 下的 popup、options 和 sidebar 頁面。它從不附加到網站的頁面或 service worker,所以網站開啟的彈出視窗(例如登入視窗)在你偵錯時照常運作。 有些網站仍會把任何帶偵錯連接埠的瀏覽器視為自動化。即使是真人操作,長按驗證等機器人檢查在開發瀏覽器裡也可能永遠通不過。要測試這類流程,請執行 extension build,然後在 chrome://extensions 開啟開發人員模式,把 dist/<browser> 載入你日常使用的瀏覽器。

搭配 AI agent

贊助 Extension.js 的平台 extension.dev 提供一個 MCP 伺服器,把這些操作以工具的形式提供給 agent。限制完全相同:助理可以自由觀察,但只有在你為該 session 啟用後才能執行動作。請見 extension.dev MCP 伺服器。

下一步