> ## 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 開發支援的瀏覽器

> 了解 Extension.js 支援哪些瀏覽器。從單一 CLI 工作流程在 Chrome、Edge、Firefox 與自訂執行檔上執行並測試擴充功能。

<AvatarBrowsers browsers={["chrome", "firefox", "edge"]} />

從單一 CLI 工作流程,在各大瀏覽器上執行並測試你的擴充功能。

從單一 CLI 驗證一個擴充功能在 Chrome、Edge、Firefox 與自訂瀏覽器執行檔上的行為。

當你需要從同一份 Extension.js 專案測試 Chrome、Firefox 或 Edge 擴充功能時,可以使用這個頁面。

## 選擇合適的目標

| 目標               | 適用情境                             | 範例                                                                          |
| ---------------- | -------------------------------- | --------------------------------------------------------------------------- |
| `chromium`       | 預設、快速的本機開發                       | `extension dev --browser=chromium`                                          |
| `chrome`         | 驗證 Chrome 特有行為                   | `extension dev --browser=chrome`                                            |
| `edge`           | 驗證 Edge 的散布行為                    | `extension dev --browser=edge`                                              |
| `firefox`        | 驗證 Gecko 相容性與 API                | `extension dev --browser=firefox`                                           |
| `chrome,firefox` | 同時對兩大引擎進行發布前檢查                   | `extension build --browser=chrome,firefox`                                  |
| `chromium-based` | 執行自訂 Chromium 執行檔(Brave、Arc 等)   | `extension dev --browser=chromium-based --chromium-binary=/path/to/browser` |
| `gecko-based`    | 執行自訂 Firefox 系列的執行檔              | `extension dev --browser=gecko-based --gecko-binary=/path/to/browser`       |
| `safari`         | 在 macOS 上建置 Safari 應用程式(需 Xcode) | `extension build --browser=safari`                                          |

## 運作方式

在 `dev`、`start`、`preview` 與 `build` 中使用 `--browser` 來選擇目標。

如果沒指定瀏覽器,CLI 預設使用 `chromium`。

`safari`(以及它的 `webkit-based` 別名)是例外:它是 **alpha**、僅限 macOS 的建置目標,只支援 `build` 與 `dev`,不支援 `preview` 或 `start`。請參見 [建置 Safari 擴充功能](/docs/browsers/safari)。

## 支援的瀏覽器

具名瀏覽器目標:

| 瀏覽器          | 用法                                     |
| ------------ | -------------------------------------- |
| **Chrome**   | `npx extension dev --browser=chrome`   |
| **Edge**     | `npx extension dev --browser=edge`     |
| **Firefox**  | `npx extension dev --browser=firefox`  |
| **Chromium** | `npx extension dev --browser=chromium` |

引擎類型目標(需自訂執行檔):

| 引擎目標                             | 用法                                                                              |
| -------------------------------- | ------------------------------------------------------------------------------- |
| **Chromium-based**               | `npx extension dev --browser=chromium-based --chromium-binary=/path/to/browser` |
| **Gecko-based**(`firefox-based`) | `npx extension dev --browser=gecko-based --gecko-binary=/path/to/browser`       |

Extension.js 在內部把 `firefox-based` 視為 Gecko 引擎目標。

## Safari 與其他 WebKit 目標

除了 Chromium 系列與 Firefox(Gecko 引擎),Extension.js 也能在 macOS 上把你的擴充功能建置成 **Safari** 應用程式。

| 目標                     | 用法                                           |
| ---------------------- | -------------------------------------------- |
| **Safari**             | `npx extension build --browser=safari`       |
| **WebKit-based**(引擎別名) | `npx extension build --browser=webkit-based` |

Safari 是**建置目標**:支援 `build` 與 `dev`,不支援 `preview` 與 `start`(Safari 擴充功能無法自動載入到執行中的瀏覽器)。它需要 macOS 與完整的 Xcode 應用程式。完整流程、需求,以及如何在 Safari 中啟用該擴充功能,請參見 [建置 Safari 擴充功能](/docs/browsers/safari)。

## 多瀏覽器選擇

你可以在一個指令中執行多個具名瀏覽器:

```bash theme={null}
npx extension dev --browser=chrome,firefox
```

使用逗號分隔的值即可依序執行多個具名目標(例如 `--browser=chrome,edge,firefox`)。

## 限制與行為

* `chromium-based` 需要 `--chromium-binary`。
* `gecko-based` / `firefox-based` 需要 `--gecko-binary`。
* 引擎類型目標會路由到同樣的 Chromium/Firefox 啟動器,但行為會依引擎調整。

## 最佳實務

* **日常迭代用具名瀏覽器**:`chrome`、`edge` 與 `firefox` 是日常測試最快的路徑。
* **有意識地使用引擎類型模式**:只在驗證自訂執行檔時才用 `chromium-based` / `gecko-based`。
* **每個瀏覽器保持設定檔隔離**:除錯時減少跨瀏覽器的狀態洩漏。
* **搭配瀏覽器專屬欄位**:用瀏覽器前綴的 manifest 鍵表達真正不同的行為。

## 後續步驟

* [自訂瀏覽器旗標](/docs/browsers/browser-flags)。
* [自訂瀏覽器偏好設定](/docs/browsers/browser-preferences)。
* [從自訂執行檔執行其他瀏覽器](/docs/browsers/running-other-browsers)。
* [在 macOS 上建置 Safari 擴充功能](/docs/browsers/safari)。