> ## 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.

# Extension.js vs WXT

> 並列比較 Extension.js 與 WXT 在打造跨瀏覽器擴充功能上的差異。涵蓋 CLI 體驗、manifest 模型、框架支援與重新載入行為。

Extension.js 與 [WXT](https://wxt.dev) 都是用來打造跨瀏覽器擴充功能的現代框架。兩者在目標上重疊,但在理念上有所差異。本頁提供事實層面的比較,幫助你依專案需求做出選擇,而不是被行銷話術左右。

## TL;DR:該選哪一個?

<CardGroup cols={2}>
  <Card title="選擇 Extension.js,如果你…">
    * 想把 **`manifest.json` 當作唯一來源**,而不是由設定產生。
    * 喜歡貼近原生 WebExtension 模型(實體檔案、透明輸出)。
    * 想用一行指令開發遠端範例:`extension dev <github-url>`。
    * 想要 Rspack 的 Rust 等級建置速度,以及一流的 [AI/MCP 工具](/docs/ai-access)。
  </Card>

  <Card title="選擇 WXT,如果你…">
    * 偏好**檔案系統慣例**(`entrypoints/`)勝於明確的 manifest。
    * 需要把 **Manifest V2** 作為主要目標。
    * 希望各處預設都使用自動 polyfill 過的 `browser.*` 命名空間。
  </Card>
</CardGroup>

本頁其餘內容會逐個維度佐證上面的摘要。

## 一覽表

| 維度                   | Extension.js                                               | WXT                                                   |
| -------------------- | ---------------------------------------------------------- | ----------------------------------------------------- |
| 打包工具                 | [Rspack](/docs/features/rspack-configuration)(Rust 為基礎)    | Vite(正在遷移到 Rolldown)                                  |
| Manifest             | 一份 `manifest.json`,瀏覽器前綴鍵會在編譯時被過濾                          | `wxt.config.ts` 在每次建置時產生 `manifest.json`              |
| 進入點                  | 從 `manifest.json` 參考的檔案                                    | `entrypoints/` 下的檔案系統慣例                               |
| 瀏覽器目標                | Chrome、Edge、Firefox、Chromium、Gecko、自訂執行檔                   | Chrome、Edge、Firefox、Safari(社群)、自訂執行檔                  |
| Manifest V3          | 預設                                                         | 預設                                                    |
| Manifest V2          | 不支援作為主要目標                                                  | 透過 `manifestVersion: 2` 支援                            |
| 重新載入模型               | popup/options/devtools 採用 HMR,content script 與 SW 採用定向重新載入 | popup/options/devtools 採用 HMR,content script 採用定向重新載入 |
| `browser.*` polyfill | `--polyfill` flag                                          | 自動 polyfill `browser` 命名空間                            |
| 範本                   | React、Preact、Vue、Svelte、TypeScript、JavaScript、init         | React、Vue、Svelte、Solid、Preact、vanilla                 |
| TypeScript           | 一流支援                                                       | 一流支援                                                  |
| AI 介面                | 託管 MCP 伺服器 + `llms.txt`([詳情](/docs/ai-access))             | 提供 `llms.txt`                                         |

## 思維模型

**Extension.js 貼近平台。** 你撰寫 `manifest.json` 並參考實體檔案。CLI 會編譯、依瀏覽器過濾、再輸出。如果你已經了解擴充功能的結構,這個框架不會擋你的路。

**WXT 把平台抽象化。** 進入點是從目錄結構推導出來(`entrypoints/popup/`、`entrypoints/content.ts`),而 manifest 則由你的設定與原始碼產生。如果你偏好慣例優於設定,WXT 為每個你寫的檔案做得更多。

兩種方式並沒有絕對的優劣。選擇取決於你想**看見**你的 manifest,還是**宣告**你的 manifest。

## CLI 介面

### Extension.js

```bash theme={null}
extension dev --browser=chrome,firefox
extension build --browser=chrome,firefox --zip
extension dev https://github.com/user/repo/tree/main/path
```

引數也可以是遠端 GitHub URL 或 ZIP 壓縮檔,適合在不 clone 的情況下啟動範例。詳見[立即開始](/docs/getting-started/immediately)。

### WXT

```bash theme={null}
wxt
wxt build
wxt build -b firefox
wxt zip
```

WXT 將 dev/build/zip 拆分為不同指令。Extension.js 則把封裝整合進 `build --zip`。

## 跨瀏覽器策略

兩個框架都用單一程式碼基底輸出多個瀏覽器,但機制不同:

* **Extension.js** 在一份 `manifest.json` 內使用[瀏覽器前綴 manifest 欄位](/docs/features/browser-specific-fields)(`chrome:`、`firefox:`、`gecko:` 等)。未加前綴的鍵套用到所有目標;加了前綴的鍵只會落到對應的建置。
* **WXT** 從 `wxt.config.ts` 與每個目標的覆寫運算 manifest。瀏覽器差異存在於 TypeScript 設定中,而不是 manifest 本身。

如果你的團隊中有設計師或 PM 會閱讀 `manifest.json`,前綴鍵可以讓那份檔案維持為唯一來源。如果你的團隊希望擴充功能設定與其他 TypeScript 設定放在一起,WXT 的做法讀起來會更自然。

## 遷移路徑

如果你目前在使用 WXT,並打算評估 Extension.js,典型的遷移工作會涉及三件事:

1. 將 `entrypoints/` 內容搬回扁平檔案,並從手寫的 `manifest.json` 參考它們。
2. 用 [`extension.config.js`](/docs/features/extension-configuration) 取代 `wxt.config.ts` 來設定建置預設值。
3. 用 `extension dev`/`extension build` 取代 `wxt`/`wxt build` 腳本。

大多數 React、Vue 與 Svelte 原始檔可以直接複製過來,毋需修改。

## 何時選擇 Extension.js

* 你想把 manifest 當作唯一來源,而不是由設定產生。
* 你想要一個 CLI 引數就能開發遠端範例(`extension dev <github-url>`)。
* 你希望文件擁有一流託管 MCP 的 AI 工具支援。
* 你希望大型擴充功能享有 Rspack 的 Rust 級編譯速度。

## 何時選擇 WXT

* 你偏好檔案系統慣例勝於明確的 manifest。
* 你需要把 Manifest V2 當作主要目標。
* 你希望各處預設都使用自動 polyfill 過的 `browser.*`。

## 延伸閱讀

* [跨瀏覽器相容性](/docs/features/cross-browser-compatibility)
* [瀏覽器專屬的 manifest 欄位](/docs/features/browser-specific-fields)
* [範本](/docs/getting-started/templates)