> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 不需點擊也能驅動執行中的擴充功能開發 session：跨所有 context 讀取日誌、檢視即時 DOM、在 service worker 中執行 eval、讀取 chrome.storage、重新載入、觸發工具列動作 — 支援 Chrome 與 Firefox、可無頭執行、可寫成腳本。

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

它在本機運作、不需要帳號，觀察永遠免費。任何會 *改變* 狀態的操作則需要在每個 session 中明確啟用。

## 開啟方式

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

```bash theme={null}
# 唯讀模式永遠開啟。加上 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`                    | [觸發工具列動作](/docs/debugging/trigger-actions-and-commands) — 開啟其 popup，或重播 `onClicked` | `--allow-control` |
| `extension open command --name <cmd>`      | [重播鍵盤快速鍵指令](/docs/debugging/trigger-actions-and-commands)                           | `--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 處理函式真的有執行嗎？

```bash theme={null}
pnpm extension eval "globalThis.__lastSyncAt" --context background --allow-eval
```

```json theme={null}
{ "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`](/docs/integrations/chrome-devtools-mcp) 以 MCP 工具的形式提供（`extension_logs`、`extension_eval`、`extension_storage`、`extension_reload`、`extension_open`、`extension_list_extensions`）。限制完全相同 — 助手可以自由觀察，但只有在你為該 session 啟用後才能執行動作。

## 下一步

* [觸發動作與鍵盤指令](/docs/debugging/trigger-actions-and-commands) — 不需點擊也能測試處理函式，可無頭執行並用於 CI。
* [同時執行兩個 MCP server](/docs/integrations/chrome-devtools-mcp) — Extension.js 控制與 Chrome DevTools MCP 並用。
* [CI 範本](/docs/workflows/ci-templates) — 將這些整合進 PR 檢核流程。