dev、start 與 preview 中透過執行檔旗標與 extension.config.* 指向任何自訂執行檔。
依名稱執行分支
這些分支是一級的瀏覽器目標。把名稱傳給--browser,Extension.js 會自動在你的系統上找到已安裝的執行檔,並透過其引擎家族的啟動器執行:
chromium:/firefox: 前綴的欄位能正確解析(參見 瀏覽器專屬 manifest 欄位)。
dev、build、start 與 preview 的說明輸出都會列出所有分支名稱。start
與 preview 的清單沒有 safari 與 webkit-based,因為這兩個指令按設計就拒絕
Safari 目標。執行自訂執行檔
若要執行沒有內建定位器的瀏覽器,或覆寫已定位的執行檔,使用下列其中一個旗標:--chromium-binary <path>--gecko-binary <path>(別名:--firefox-binary <path>)
執行檔功能
CLI 範例
start 與 preview 使用。
依作業系統找出執行檔路徑
執行檔旗標要的是可執行檔。無效的路徑會立即以錯誤失敗,而不是啟動。macOS
在 macOS 上,/Applications/Brave Browser.app 這樣的 app 是資料夾,不是可執行檔。要傳入 bundle 內位於 Contents/MacOS 的可執行檔:
Windows
把路徑加上引號並使用正斜線,所有 shell 都接受:C:\\Program Files\\...。
Linux
傳入套件管理器安裝的可執行檔:PATH 上時,執行 which brave-browser 印出路徑。
在 extension.config.* 中設定
目標對應行為
執行檔提示會對應到引擎目標:chromiumBinary→chromium-basedgeckoBinary/firefoxBinary→gecko-based
可用的瀏覽器
有內建定位器的分支可依名稱執行;其他則以執行檔旗標執行:重要限制
-
chromium-based需要--chromium-binary(或設定中的chromiumBinary)。沒有它,啟動會直接以錯誤結束,不會回退到系統瀏覽器。 -
gecko-based/firefox-based需要有效的geckoBinary路徑。 -
librewolf需要在每台機器上開啟一次遠端偵錯。LibreWolf 每次啟動都會把devtools.debugger.remote-enabled重設為false,覆寫 Extension.js 建立的設定檔,因此啟動前會檢查~/.librewolf/librewolf.overrides.cfg(Windows 上為%USERPROFILE%\.librewolf\librewolf.overrides.cfg),缺少時會停止並列出需要加入的兩行: - 無效路徑會立即失敗,並回報明確的 CLI/執行階段錯誤。
-
build不接受執行檔旗標。基於執行檔的啟動方式只能用在dev、start與preview。
執行檔變數
設定一個環境變數,即可在不更動設定的情況下,用指定的執行檔啟動某個具名目標:
從 4.1.39 之後的版本起,每個瀏覽器都依同一個順序解析執行檔。先是旗標,接著是變數、受管理的執行檔,最後是系統安裝。
若該路徑不存在或無法執行,啟動會以
E_BROWSER_BINARY_INVALID 失敗,而不會靜默回退。身分卡片會寫明選定執行檔的那個變數,例如 (pinned with EDGE_BINARY)。見執行檔如何選定。
不啟動瀏覽器執行
有時候正確的瀏覽器數量是零,例如在容器裡、透過 SSH,或當你自己驅動瀏覽器時。 把--no-browser 傳給 dev、start 或 preview:
(no-browser mode) 橫幅。
把那個 dist/<browser> 資料夾載入你已經在執行的瀏覽器。在 Chromium 系瀏覽器中,開啟開發人員模式後在 chrome://extensions 選擇「Load unpacked」。載入的擴充功能會在存檔時持續更新。關於用 --wait 做就緒同步,參見 dev。
要讓某個指令預設如此,在設定中設定 noBrowser。CLI 旗標優先於設定值:
退出注入的預設值
dev、start 與 preview 會把啟動預設值注入每個 session。一個看得見的預設值是深色外觀。Chromium 目標會拿到 --force-dark-mode 與 --enable-features=WebUIDarkMode 旗標。Gecko 目標會拿到對應的深色偏好設定。
要保留你的系統外觀,把旗標列在 excludeBrowserFlags:
--force-dark-mode 會拿掉整組外觀設定,包括 Gecko 的偏好設定。排除項目也會依切換參數名稱比對,因此 --enable-features 會移除 --enable-features=WebUIDarkMode。預設旗標清單與完整排除規則參見 瀏覽器旗標。
最佳實務
- 執行檔搭配明確的瀏覽器目標:使用
--browser=chromium-based或--browser=gecko-based表達清楚意圖。 - 使用絕對路徑:避免 shell 路徑解析造成的問題。
- 在持續整合(CI)Runner 中固定版本:讓瀏覽器執行檔路徑在自動化檢查中保持確定性。
- 小心搭配設定檔/旗標:沿用具名瀏覽器目標所使用的設定檔與旗標策略。

