從終端機除錯執行中的瀏覽器擴充功能

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

開啟方式

啟動帶有你所需控制旗標的開發 session：

# 唯讀模式永遠開啟。加上 control 才能對擴充功能執行動作：
pnpm extension dev --allow-control

# 再加上 eval 以便在 context 中執行任意運算式：
pnpm extension dev --allow-control --allow-eval

以下每個操作都會作用在該 session，並以相同的方式指定 context，無論是讀取或執行動作。

你可以做什麼

指令	用途	限制
`extension logs`	將所有 context（SW、content、popup、options、sidebar、devtools）的日誌串流為單一有序時間線	—
`extension inspect`	讀取某個介面注入後的即時 DOM	—
`extension storage get \| set`	讀取或寫入擴充功能的 `chrome.storage`	`--allow-control`
`extension reload`	重新載入擴充功能或某個分頁	`--allow-control`
`extension open <popup\|options\|sidebar>`	開啟某個擴充功能介面	`--allow-control`
`extension open action`	觸發工具列動作 — 開啟其 popup，或重播 `onClicked`	`--allow-control`
`extension open command --name <cmd>`	重播鍵盤快速鍵指令	`--allow-control`
`extension eval "<expr>" --context <c>`	在某個 context 中執行運算式並回傳結果	`--allow-eval`

指定 context

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

位址	意義
`--context background`	service worker（或 MV2 背景頁面）
`--context popup` / `options` / `sidebar`	該擴充功能介面（如果已開啟）
`--context content --url "https://shop.example/*"`	在符合網址的頁面上的隔離 content world
`--context content --tab 7`	指定分頁中的 content world

範例：我的 background 處理函式真的有執行嗎？

pnpm extension eval "globalThis.__lastSyncAt" --context background --allow-eval

{ "ok": true, "value": 1718000000000 }

你的運算式所觸發的任何 console.log，同時會經由 extension logs 流出，並以序號相互關聯 — 因此你能同時看到回傳值以及副作用。

跨瀏覽器支援

Extension.js 透過瀏覽器內的伴隨程式進行除錯，而非 Chrome DevTools Protocol，因此核心流程能觸及你自己的介面，在 Chrome 與 Firefox 上都可運作 — 過去「Firefox 用 RDP，不支援」的那堵牆，對這些工具而言已經不存在。

功能	Chromium	Firefox
`logs`、`inspect`、`eval`、`storage`、`reload`、`open`（含 `action`/`command`）	✓	✓（已驗證）
`inspect --deep-dom`（封閉的 shadow root）	✓	—（使用 CDP）
`extension_list_extensions`（MCP 工具）	✓	—（使用 CDP）

（extension_list_extensions 是 MCP 工具而非 CLI 動詞 — 它透過 DevTools Protocol 連線，所以僅限 Chromium。）

安全性

這些限制有其用意，並非繁文縟節：

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

搭配 AI agent

同樣的操作會透過 @extension.dev/mcp 以 MCP 工具的形式提供（extension_logs、extension_eval、extension_storage、extension_reload、extension_open、extension_list_extensions）。限制完全相同 — 助手可以自由觀察，但只有在你為該 session 啟用後才能執行動作。

下一步

觸發動作與鍵盤指令 — 不需點擊也能測試處理函式，可無頭執行並用於 CI。
同時執行兩個 MCP server — Extension.js 控制與 Chrome DevTools MCP 並用。
CI 範本 — 將這些整合進 PR 檢核流程。

用一個 STORE.md 管理商店中繼資料不用點擊就能測試工具列動作或鍵盤指令

⌘I

Introduction

Browser extension fundamentals

Getting started

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Debugging

Implementation guide

Community

從終端機除錯執行中的瀏覽器擴充功能

開啟方式

你可以做什麼

指定 context

範例：我的 background 處理函式真的有執行嗎？

跨瀏覽器支援

安全性

搭配 AI agent

下一步

​開啟方式

​你可以做什麼

​指定 context

​範例：我的 background 處理函式真的有執行嗎？

​跨瀏覽器支援

​安全性

​搭配 AI agent

​下一步

開啟方式

你可以做什麼

指定 context

範例：我的 background 處理函式真的有執行嗎？

跨瀏覽器支援

安全性

搭配 AI agent

下一步