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

開啟方式

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

你可以做什麼

指定 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 contentextension_eval MCP 工具正是基於這個原因,在 Chromium MV3 session 上預設使用 page context;在 Firefox/MV2 上其預設值仍為 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_list_extensions 是 MCP 工具而非 CLI 動詞 — 它透過 DevTools Protocol 連線,所以僅限 Chromium。)

安全性

這些限制有其用意,並非繁文縟節:
  • 觀察不需要任何權限。 讀取日誌與 DOM 隨時可用。
  • 有界限的操作需要 --allow-control storagereloadopen 會改變狀態,因此你必須在每個 session 中明確啟用。
  • eval 需要 --allow-eval 以及 每個 session 的權杖。 權杖會寫入 dist/ 外的 0600 檔案,因此絕不會包含在建置產物中 — 隨機的本機程序無法悄悄操控你的 service worker。
  • 絕不會進入正式環境。 控制通道只在 dev/preview 期間存在,且綁定在已建置產物中不存在的連接埠上。

搭配 AI agent

同樣的操作會透過 @extension.dev/mcp 以 MCP 工具的形式提供(extension_logsextension_evalextension_storageextension_reloadextension_openextension_list_extensions)。限制完全相同 — 助手可以自由觀察,但只有在你為該 session 啟用後才能執行動作。

下一步