install 把受管理的瀏覽器執行階段加入 Extension.js 的快取。
當你想為 dev、build、start 或 preview 使用一致的瀏覽器執行檔時,這個功能特別實用。它支援 Chrome for Testing、Chromium、Firefox 與 Edge。
何時使用 install
- 你需要一致、可重複的瀏覽器執行檔,以利持續整合(CI)、自動化或團隊在本機共用相同版本。
- 你想用 Chrome for Testing,而不依賴系統已安裝的 Chrome 版本。
- 你正在使用受管理的 Firefox 或 Edge 執行階段建立跨瀏覽器測試環境。
為什麼 Extension.js 會下載瀏覽器
執行類指令偏好受管理的瀏覽器執行階段,而不是你日常使用的瀏覽器。- 受管理的執行檔有固定版本。
dev、CI 執行與團隊成員都會啟動同一個建置。 - Chrome for Testing 是為自動化打造的。近期的品牌版 Chrome 建置(150+)可能移除用來載入擴充功能的
--load-extension切換參數。 - 受管理的執行階段在隔離的設定檔中執行。它永遠不會碰到你的個人瀏覽器、它的設定檔或它的設定。
install。當請求的目標沒有可用的執行檔時,執行類指令會印出確切的安裝指令。
略過受管理下載
你可以直接對已安裝的瀏覽器開發,不需任何下載:- 依名稱執行分支:
extension dev --browser=brave會為你定位已安裝的 Brave。參見 執行其他瀏覽器。 - 固定任何執行檔:把
--chromium-binary <path>或--gecko-binary <path>傳給dev、start或preview。這個固定值會覆寫所有定位器。 - 請求
edge時,若沒有受管理的 Edge,會啟動系統上已安裝的 Edge。 - 請求
chrome時,會拒絕品牌版的系統 Chrome,並要求改用 Chrome for Testing。 - 無論如何都要執行品牌版 Chrome 時,用
--chromium-binary固定它。
系統已安裝 Edge 時
--browser=edge 會自行找到系統的 Edge,所以你可以略過 extension install edge。只有在你想要一份固定版本、供自動化使用的受管理副本時,才執行 extension install edge。
在 Linux 上,受管理的 Edge 下載需要具備 sudo 權限的互動式工作階段。當下載失敗且系統存在 Edge 時,安裝程式會回報系統執行檔,並以它成功完成。
標準用法
單一瀏覽器使用位置引數形式:all 時,才使用 --browser。
Install 指令功能
用法
引數與旗標
這裡的 all 是什麼意思
extension install --browser all 會安裝 chrome、chromium、edge 與 firefox。這與執行類指令上的 --browser all 不同,後者只展開為 chrome、edge 與 firefox。安裝集合也包含 Chromium,因為它是 dev 與 start 的預設啟動目標。
用 --output json 取得機器可讀輸出
--output json 會在 stdout 印出一個 schema-1 信封:
- 成功的安裝會印出一個
status: "installed"框,已安裝的瀏覽器在value.browsers中。 --where會印出一個status: "located"框,解析後的路徑在value.paths中。- 下載失敗會在行程以
1結束前印出ok: false,其error.code: "E_BROWSER_DOWNLOAD"。
範例
安裝 Chrome for Testing
在一個指令中安裝多個目標
顯示 Chrome 的受管理安裝路徑
快取位置
預設情況下,Extension.js 會把受管理的瀏覽器存放在使用者層級、穩定的快取中:- macOS:
~/Library/Caches/extension.js/browsers - Linux:
~/.cache/extension.js/browsers或$XDG_CACHE_HOME/extension.js/browsers - Windows:
%LOCALAPPDATA%\extension.js\browsers
EXT_BROWSERS_CACHE_DIR 覆寫快取根目錄。
快取裡放了什麼
每個瀏覽器在快取根目錄下都有自己的資料夾,但資料夾內部的配置會因下載引擎而異:chrome、chromium與firefox來自@puppeteer/browsers。每個瀏覽器目錄裡會有它那套巢狀的平台與版本資料夾。edge來自playwright install msedge,它以自己的結構擺放執行檔。safari沒有可下載的內容。Safari 隨 macOS 一起提供,建置還需要完整的 Xcode 應用程式,所以extension install safari會附上說明並拒絕執行。- 像 Brave 這樣的具名分支永遠不會被下載。請改用
--chromium-binary或--gecko-binary指向它們。
--where,不要把路徑寫死,因為巢狀配置可能隨下載引擎改變。
專案本地的執行檔
設定EXTENSIONJS_BINARIES_IN_DIST=1,可讓執行類指令在專案內的 dist/extension-js/binaries 下解析受管理的執行檔,而不是共用的使用者層級快取。這適合沙箱化或完全自足的專案設定。
最佳實務
- 在 CI 中使用
install,以固定一致的瀏覽器執行檔,不依賴 runner 所提供的版本。 - 優先使用
chrome而非chromium:Chrome for Testing 較貼近穩定版 Chrome 的行為。 - 使用
--where在撰寫受管理瀏覽器自動化前先確認快取路徑。 install只管理 Extension.js 快取內的瀏覽器。它不會更動系統上的瀏覽器安裝。
行為說明
chrome會安裝 Chrome for Testing,而不是依賴系統的 Google Chrome 應用程式。edge在 Linux 上可能需要具備權限的互動式工作階段。