> ## 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 app。完整工作流、要求以及如何在 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`。
* **每个浏览器保持 profile 隔离**：减少调试时的跨浏览器状态泄漏。
* **配合按浏览器划分的字段**：用带浏览器前缀的 manifest 键处理真正的行为差异。

## 下一步

* [自定义浏览器 flag](/docs/browsers/browser-flags)。
* [自定义浏览器 preferences](/docs/browsers/browser-preferences)。
* [用自定义二进制运行其他浏览器](/docs/browsers/running-other-browsers)。
* [在 macOS 上构建 Safari 扩展](/docs/browsers/safari)。