> ## 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` 中使用執行檔旗標與 `extension.config.*`。

## 運作方式

使用下列其中一個旗標:

* `--chromium-binary <path>`
* `--gecko-binary <path>`(別名:`--firefox-binary <path>`)

不論你選擇的具名瀏覽器目標為何,這些執行檔旗標都會覆寫 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 執行檔。

## 可用的瀏覽器

可透過執行檔旗標執行的常見瀏覽器:

| 瀏覽器名稱                         | 類型                 | CLI 旗標              | 官方網站                                                      |
| ----------------------------- | ------------------ | ------------------- | --------------------------------------------------------- |
| **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` 不接受執行檔旗標。基於執行檔的啟動方式只能用在 `dev`、`start` 與 `preview`。

## 最佳實務

* **執行檔搭配明確的瀏覽器目標**:使用 `--browser=chromium-based` 或 `--browser=gecko-based` 表達清楚意圖。
* **使用絕對路徑**:避免 shell 路徑解析造成的問題。
* **在持續整合(CI)Runner 中固定版本**:讓瀏覽器執行檔路徑在自動化檢查中保持確定性。
* **小心搭配設定檔/旗標**:沿用具名瀏覽器目標所使用的設定檔與旗標策略。

## 後續步驟

* 進一步了解 [瀏覽器偏好設定](/docs/browsers/browser-preferences)。
* 進一步了解 [瀏覽器設定檔](/docs/browsers/browser-profile)。