跳轉到主要內容
使用 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。這個固定值會覆寫所有定位器。
  • 設定一個執行檔變數,例如 FIREFOX_BINARY。見執行哪個執行檔。
  • 請求 edge 時,會啟動系統上已安裝的 Edge。
  • 請求 chrome 時,會拒絕品牌版的系統 Chrome,並要求改用 Chrome for Testing。
  • 無論如何都要執行品牌版 Chrome 時,用 --chromium-binary 固定它。

Edge 安裝在你的系統上

extension install edge 會執行 playwright install msedge,它把 Microsoft Edge 安裝到你的系統上。Extension.js 的快取裡沒有固定版本的 Edge 副本。--browser=edge 會自行找到系統的 Edge,所以 Edge 已經安裝時你可以略過這個指令。 在 Linux 上,這次安裝需要具備 sudo 權限的互動式工作階段。當安裝失敗且系統存在 Edge 時,安裝程式會回報系統執行檔,並以它成功完成。 從 4.2.0 起,當 install 找到的 Edge 位於執行指令不會搜尋的位置時,訊息會印出它的路徑,並請你用 --chromium-binary 傳入這個路徑。

執行哪個執行檔

從 4.1.39 之後的版本起,dev、start 與 preview 對每個瀏覽器都依同一個順序選定執行檔:
  1. 旗標:--chromium-binary 或 --gecko-binary。
  2. 該瀏覽器的環境變數。
  3. 來自 extension install 的受管理執行檔。
  4. 系統安裝。
變數指向不存在的路徑或無法執行的檔案時,啟動會以 E_BROWSER_BINARY_INVALID 失敗。出錯的變數絕不會被略過。 身分卡片會說明是哪一步給出了結果。(pinned with FIREFOX_BINARY) 寫明那個旗標或變數,(system install) 表示瀏覽器來自你的系統。受管理的執行檔沒有任何標註。ready.json 用 binaryProvenance 與 binaryPinnedBy 記錄同一件事。 對 Firefox 來說,受管理這一步會優先選擇穩定版,而不是同一個快取裡的 nightly。執行的是 nightly 時,卡片會顯示 Firefox Nightly。 請求 chrome 時仍然會拒絕品牌版的系統 Chrome。指向品牌版 Chrome 的變數不會被採用,執行會繼續使用受管理的執行檔。見執行檔如何選定。

標準用法

單一瀏覽器使用位置引數形式:
只有在你需要多目標、引擎家族或 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"。
  • 下載結束了卻沒有留下可用的瀏覽器執行檔時,也以同樣的方式失敗。見行為說明。
  • 從 4.1.41 之後的版本起,缺少套件執行器時改為以 E_BROWSER_INSTALLER_NOT_FOUND 失敗。
  • 從 4.2.0 之後的版本起,存在但無法啟動的套件執行器會以 E_BROWSER_DOWNLOAD 失敗。訊息會指名執行器與系統錯誤代碼,並說明什麼都沒有下載。
  • 從 4.2.0 之後的版本起,類型未知的安裝故障會以 E_INTERNAL 失敗。提示會請你重新執行安裝,並在同樣失敗時回報這則訊息。
從 4.2.0 起,這些失敗有各自的代碼:

範例

安裝 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 會把 Microsoft Edge 安裝到你的系統上。
  • 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 把 chrome、chromium 與 firefox 放在 Extension.js 快取裡,不會更動這些瀏覽器的系統安裝。
  • edge 是例外。它會把 Microsoft Edge 安裝到你的系統上。

行為說明

  • chrome 會安裝 Chrome for Testing,而不是依賴系統的 Google Chrome 應用程式。
  • edge 在 Linux 上可能需要具備權限的互動式工作階段。
  • install 在回報成功之前會檢查目標資料夾。當安裝程式正常結束,但資料夾裡沒有一個非空且可執行的瀏覽器執行檔時(例如下載被中斷之後),指令會以 E_BROWSER_DOWNLOAD 失敗並以 1 結束。它會刪掉不完整的檔案,所以下一次 extension install 從乾淨的狀態開始。
  • 從 4.2.0 起,EXTENSION_INSTALL_TIMEOUT_MS 設定安裝程式可以執行多久,預設 30 分鐘。值是一個整數毫秒數。任何其他值,例如 30s,都代表預設值。
  • 從 4.2.0 起,同一個瀏覽器一次只執行一個安裝。安裝會在快取根目錄中持有一個以瀏覽器命名的鎖資料夾,例如 .chrome.lock。同一瀏覽器的第二次安裝會等待它,最長等到安裝逾時,然後以 E_BROWSER_INSTALL_BUSY 失敗。訊息會指名在沒有這樣的安裝執行時可以刪除的鎖資料夾。持有者處理程序已經不在的鎖會被接管。
  • 從 4.2.0 起,install 在下載開始之前會把一個 .extension-install.json 標記寫入瀏覽器資料夾。帶有該標記的資料夾,或只包含下載引擎所寫檔案的資料夾,屬於 Extension.js。同時還包含瀏覽器 profile 的帶標記資料夾則不屬於。install 與 uninstall 不會從不屬於 Extension.js 的資料夾中移除任何內容。
  • 在 Deno 上,install 需要 PATH 裡有 Node.js。瀏覽器安裝器會呼叫 npx(或啟動 CLI 的那個套件管理器)來執行下載引擎,而 deno 沒有這樣的執行器。沒有 Node.js 時,指令會在下載步驟失敗。其他指令只靠 Deno 就能執行。

後續步驟