> ## 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 显式提供二进制路径，在 Brave、Vivaldi、Waterfox 或其他 Chromium 与 Gecko 浏览器中测试扩展。

<AvatarBrowsers browsers={["waterfox", "opera", "brave"]} />

通过显式提供二进制路径，运行除默认具名目标之外的 Chromium 与 Gecko 家族浏览器。

在同一套 Extension.js 工作流中测试自定义浏览器二进制（例如 Brave、Vivaldi 或 Waterfox）。可在 `dev`、`start` 与 `preview` 中使用二进制 flag 与 `extension.config.*`。

## 工作原理

使用以下任一 flag：

* `--chromium-binary <path>`
* `--gecko-binary <path>`（别名：`--firefox-binary <path>`）

无论你选择了哪个具名浏览器目标，这些二进制 flag 都会覆盖 Extension.js 实际启动的浏览器二进制。

## 二进制能力

| 选项 / 键                            | 作用                         |
| --------------------------------- | -------------------------- |
| `--chromium-binary <path>`        | 启动自定义的 Chromium 家族浏览器二进制。  |
| `--gecko-binary <path>`           | 启动自定义的 Gecko 家族浏览器二进制。     |
| `--firefox-binary <path>`         | `--gecko-binary` 的别名。      |
| `browser.<target>.chromiumBinary` | 在配置中设置默认的自定义 Chromium 二进制。 |
| `browser.<target>.geckoBinary`    | 在配置中设置默认的自定义 Gecko 二进制。    |
| `commands.<name>.chromiumBinary`  | 为特定命令设置自定义 Chromium 二进制。   |
| `commands.<name>.geckoBinary`     | 为特定命令设置自定义 Gecko 二进制。      |

### CLI 示例

```bash theme={null}
extension dev --browser=chromium-based --chromium-binary="/path/to/brave"
```

```bash theme={null}
extension dev --browser=firefox --gecko-binary="/path/to/firefox-developer-edition"
```

它们也可以与 `start` 和 `preview` 搭配使用。

## 在 `extension.config.*` 中配置

```js theme={null}
export default {
  browser: {
    "chromium-based": {
      chromiumBinary: "/path/to/custom-chromium-browser",
    },
    "gecko-based": {
      geckoBinary: "/path/to/custom-gecko-browser",
    },
  },
};
```

你也可以把二进制路径放在命令块中：

```js theme={null}
export default {
  commands: {
    dev: {
      chromiumBinary: "/path/to/custom-chromium-browser",
    },
    preview: {
      geckoBinary: "/path/to/custom-gecko-browser",
    },
  },
};
```

## 目标映射行为

二进制提示会映射到引擎目标：

* `chromiumBinary` → `chromium-based`
* `geckoBinary` / `firefoxBinary` → `gecko-based`

如果两者都提供，Extension.js 会先解析 Chromium 二进制。

## 可用浏览器

可通过二进制 flag 运行的常见浏览器：

| 浏览器名称                         | 类型                 | CLI flag            | 官方网站                                                      |
| ----------------------------- | ------------------ | ------------------- | --------------------------------------------------------- |
| **Brave**                     | Chromium-based 浏览器 | `--chromium-binary` | [brave.com](https://brave.com)                            |
| **Opera**                     | Chromium-based 浏览器 | `--chromium-binary` | [opera.com](https://www.opera.com)                        |
| **Vivaldi**                   | Chromium-based 浏览器 | `--chromium-binary` | [vivaldi.com](https://vivaldi.com)                        |
| **Waterfox**                  | Gecko-based 浏览器    | `--gecko-binary`    | [Waterfox](https://www.waterfox.net)                      |
| **Firefox Developer Edition** | Gecko-based 浏览器    | `--gecko-binary`    | [firefox.com](https://www.mozilla.org/firefox/developer/) |

## 重要约束

* `chromium-based` 需要一个有效的 `chromiumBinary` 路径。
* `gecko-based` / `firefox-based` 需要一个有效的 `geckoBinary` 路径。
* 无效路径会以清晰的 CLI / 运行时错误立即失败。
* `build` 不接受二进制 flag。基于二进制的启动只能配合 `dev`、`start` 与 `preview` 使用。

## 最佳实践

* **二进制与显式浏览器目标搭配**：使用 `--browser=chromium-based` 或 `--browser=gecko-based`，让意图更可预期。
* **使用绝对路径**：避免与 shell 相关的路径解析问题。
* **在 CI runner 上锁定版本**：让浏览器二进制路径在自动化检查中保持确定性。
* **谨慎与 profile / flag 组合**：复用与具名浏览器目标相同的 profile 与 flag 策略。

## 下一步

* 进一步了解 [浏览器 preferences](/docs/browsers/browser-preferences)。
* 进一步了解 [浏览器 profile](/docs/browsers/browser-profile)。