以執行檔路徑執行其他瀏覽器

執行熱門的 Chromium 與 Gecko 分支,可以用名稱(Extension.js 會為你定位已安裝的執行檔)或提供明確的執行檔路徑。從同一份 Extension.js 工作流程測試 Brave、Opera、Vivaldi、Yandex、Waterfox 與 LibreWolf。直接指定分支名稱,或在 dev、start 與 preview 中透過執行檔旗標與 extension.config.* 指向任何自訂執行檔。

依名稱執行分支

這些分支是一級的瀏覽器目標。把名稱傳給 --browser,Extension.js 會自動在你的系統上找到已安裝的執行檔,並透過其引擎家族的啟動器執行:

瀏覽器目標	引擎家族	自動定位
`brave`	Chromium	是
`opera`	Chromium	是
`vivaldi`	Chromium	是
`yandex`	Chromium	是
`waterfox`	Gecko	是
`librewolf`	Gecko	是

extension dev --browser=brave

extension dev --browser=waterfox

如果該瀏覽器未安裝,Extension.js 會以安裝指引結束。具名分支會繼承其家族的 manifest 鍵,因此 chromium:/firefox: 前綴的欄位能正確解析(參見瀏覽器專屬 manifest 欄位)。

dev、build、start 與 preview 的說明輸出都會列出所有分支名稱。start 與 preview 的清單沒有 safari 與 webkit-based,因為這兩個指令按設計就拒絕 Safari 目標。

執行自訂執行檔

若要執行沒有內建定位器的瀏覽器,或覆寫已定位的執行檔,使用下列其中一個旗標:

--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 範例

extension dev --browser=chromium-based --chromium-binary="/path/to/brave"

extension dev --browser=firefox --gecko-binary="/path/to/firefox-developer-edition"

也可以搭配 start 與 preview 使用。

依作業系統找出執行檔路徑

執行檔旗標要的是可執行檔。無效的路徑會立即以錯誤失敗,而不是啟動。

macOS

在 macOS 上,/Applications/Brave Browser.app 這樣的 app 是資料夾,不是可執行檔。要傳入 bundle 內位於 Contents/MacOS 的可執行檔:

extension dev --browser=chromium-based --chromium-binary="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"

可執行檔名稱可能與 app 名稱不同。列出資料夾內容來找到它:

ls "/Applications/Brave Browser.app/Contents/MacOS"

Windows

把路徑加上引號並使用正斜線,所有 shell 都接受:

extension dev --browser=chromium-based --chromium-binary="C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"

反斜線也可以,但許多 shell 要求你把它們寫成兩個,例如 C:\\Program Files\\...。

Linux

傳入套件管理器安裝的可執行檔:

extension dev --browser=chromium-based --chromium-binary="/usr/bin/brave-browser"

當執行檔在你的 PATH 上時,執行 which brave-browser 印出路徑。

在 `extension.config.*` 中設定

export default {
  browser: {
    "chromium-based": {
      chromiumBinary: "/path/to/custom-chromium-browser",
    },
    "gecko-based": {
      geckoBinary: "/path/to/custom-gecko-browser",
    },
  },
};

你也可以把執行檔路徑放在指令區塊中:

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 執行檔。

可用的瀏覽器

有內建定位器的分支可依名稱執行;其他則以執行檔旗標執行:

瀏覽器名稱	類型	執行方式	官方網站
Brave	Chromium-based 瀏覽器	`--browser=brave` 或 `--chromium-binary`	brave.com
Opera	Chromium-based 瀏覽器	`--browser=opera` 或 `--chromium-binary`	opera.com
Vivaldi	Chromium-based 瀏覽器	`--browser=vivaldi` 或 `--chromium-binary`	vivaldi.com
Yandex	Chromium-based 瀏覽器	`--browser=yandex` 或 `--chromium-binary`	browser.yandex.com
Waterfox	Gecko-based 瀏覽器	`--browser=waterfox` 或 `--gecko-binary`	Waterfox
LibreWolf	Gecko-based 瀏覽器	`--browser=librewolf` 或 `--gecko-binary`	librewolf.net
Firefox Developer Edition	Gecko-based 瀏覽器	`--gecko-binary`	firefox.com

重要限制

chromium-based 需要 --chromium-binary(或設定中的 chromiumBinary)。沒有它,啟動會直接以錯誤結束,不會回退到系統瀏覽器。
gecko-based / firefox-based 需要有效的 geckoBinary 路徑。
無效路徑會立即失敗,並回報明確的 CLI/執行階段錯誤。
build 不接受執行檔旗標。基於執行檔的啟動方式只能用在 dev、start 與 preview。

Edge 執行檔覆寫

設定 EDGE_BINARY 環境變數,即可在不更動設定的情況下,用指定的執行檔啟動 --browser=edge:

EDGE_BINARY="/path/to/msedge" extension dev --browser=edge

若該路徑不存在,啟動會直接失敗,而不會靜默回退。

不啟動瀏覽器執行

有時候正確的瀏覽器數量是零,例如在容器裡、透過 SSH,或當你自己驅動瀏覽器時。把 --no-browser 傳給 dev、start 或 preview:

extension dev --no-browser

開發迴圈仍然完整。伺服器監看你的檔案,每次重建都會廣播一次重新載入。第一次成功編譯後,終端機會印出標明輸出資料夾的 (no-browser mode) 橫幅。把那個 dist/<browser> 資料夾載入你已經在執行的瀏覽器。在 Chromium 系瀏覽器中,開啟開發人員模式後在 chrome://extensions 選擇「Load unpacked」。載入的擴充功能會在存檔時持續更新。關於用 --wait 做就緒同步,參見 dev。要讓某個指令預設如此,在設定中設定 noBrowser。CLI 旗標優先於設定值:

export default {
  commands: {
    dev: {
      noBrowser: true,
    },
  },
};

退出注入的預設值

dev、start 與 preview 會把啟動預設值注入每個 session。一個看得見的預設值是深色外觀。Chromium 目標會拿到 --force-dark-mode 與 --enable-features=WebUIDarkMode 旗標。Gecko 目標會拿到對應的深色偏好設定。要保留你的系統外觀,把旗標列在 excludeBrowserFlags:

export default {
  browser: {
    "chromium-based": {
      chromiumBinary: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
      excludeBrowserFlags: ["--force-dark-mode"],
    },
  },
};

排除 --force-dark-mode 會拿掉整組外觀設定,包括 Gecko 的偏好設定。排除項目也會依切換參數名稱比對,因此 --enable-features 會移除 --enable-features=WebUIDarkMode。預設旗標清單與完整排除規則參見瀏覽器旗標。

最佳實務

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

後續步驟

進一步了解瀏覽器偏好設定。
進一步了解瀏覽器設定檔。

Introduction

Browser extension fundamentals

Getting started

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

以執行檔路徑執行其他瀏覽器

依名稱執行分支

執行自訂執行檔

執行檔功能

CLI 範例

依作業系統找出執行檔路徑

macOS

Windows

Linux

在 `extension.config.*` 中設定

目標對應行為

可用的瀏覽器

重要限制

Edge 執行檔覆寫

不啟動瀏覽器執行

退出注入的預設值

最佳實務

後續步驟

​依名稱執行分支

​執行自訂執行檔

​執行檔功能

​CLI 範例

​依作業系統找出執行檔路徑

​macOS

​Windows

​Linux

​在 extension.config.* 中設定

​目標對應行為

​可用的瀏覽器

​重要限制

​Edge 執行檔覆寫

​不啟動瀏覽器執行

​退出注入的預設值

​最佳實務

​後續步驟

依名稱執行分支

執行自訂執行檔

執行檔功能

CLI 範例

依作業系統找出執行檔路徑

macOS

Windows

Linux

在 `extension.config.*` 中設定

目標對應行為

可用的瀏覽器

重要限制

Edge 執行檔覆寫

不啟動瀏覽器執行

退出注入的預設值

最佳實務

後續步驟