跳轉到主要內容
從單一 CLI 工作流程,在各大瀏覽器上執行並測試你的擴充功能。 從單一 CLI 驗證一個擴充功能在 Chrome、Edge、Firefox、Safari 與自訂瀏覽器執行檔上的行為。 當你需要從同一份 Extension.js 專案測試 Chrome、Firefox、Edge 或 Safari 擴充功能時,可以使用這個頁面。

選擇合適的目標

運作方式

在 dev、start、preview 與 build 中使用 --browser 來選擇目標。 如果沒指定瀏覽器,CLI 預設使用 chromium。 --browser 只接受下列這些值,可以單獨使用,也可以用逗號分隔:
--browser=all 也會被接受,它會展開為 chrome, edge, firefox。 從 4.2.0 起,空值(例如 --browser=,或 --browser=chrome, 中的空項目)會以 E_UNSUPPORTED_BROWSER 與結束碼 1 被拒絕,什麼都不會執行。訊息為 --browser got an empty value.,並列出可選的值。在 --output json 下,這次拒絕的狀態為 usage。
開發時請優先使用 chromium(或透過 npx extension install chrome 安裝的 Chrome for Testing),而不是品牌版 Chrome。較新的品牌版 Chrome 版本(150+)會捨棄 --load-extension 開關,除非有原則停用該行為。被捨棄的開關 看起來和一次正常啟動完全一樣。當 Extension.js 無法確認載入成功時,它會發出警告, 並指引你前往 chrome://extensions。
safari(以及它的 webkit-based 別名)是例外:它是僅限 macOS 的目標,build 與 dev 支援它,preview 與 start 不支援。Safari 的 dev 工作階段會輸出記錄,並在儲存後重新載入。請參見 建置 Safari 擴充功能。 chromium-emulator(從 4.1.38 起)同樣是開發目標:dev 會開啟一個模擬的 Chromium,在網頁中執行你的擴充功能;build 會寫出 dist/chromium-emulator。start 與 preview 會以 E_UNSUPPORTED_BROWSER 拒絕它,因為這個頁面要從開發伺服器讀取你的建置。請參見 dev 指令中的「模擬的 Chromium」一節。

請求的目標 vs. 啟動的執行檔

你請求的瀏覽器決定產物。執行檔只是執行時。 當你執行 extension dev --browser=chromium 時,Extension.js 一律會:
  • 把輸出寫到 dist/chromium(資料夾以請求的目標命名,絕不會以啟動它的執行檔命名)。
  • 為請求的目標解析瀏覽器專屬的 manifest 欄位。
如果請求的瀏覽器沒有安裝,Extension.js 不會更動目標。對 chrome 與 chromium,它會尋找另一個受管理的 Chromium 系列執行檔(先前由 npx extension install 下載的),改用它作為執行時:
  • 請求 chromium 但缺少:回退到受管理的 Chrome,再回退到受管理的 Edge。
  • 請求 chrome 但缺少:回退到受管理的 Chromium,再回退到受管理的 Edge。
發生這種情況時,CLI 會印出一則警告,指出缺少的瀏覽器與修正方式,例如 npx extension install chromium。這則警告刻意不寫出替代執行檔的路徑。請從 ready.json 的 binary 讀取這個路徑。輸出資料夾與產出的 manifest 與沒有回退時完全相同。

--browser=edge 執行的是什麼

edge 永遠不會換成另一個瀏覽器,它也沒有固定版本的受管理副本。npx extension install edge 透過 Playwright 把 Microsoft Edge 安裝到你的系統上。Extension.js 依這個順序解析 Edge 執行檔:
  1. --chromium-binary 中的路徑(有傳入時)。
  2. EDGE_BINARY 環境變數中的路徑(有設定時)。
  3. 系統上已安裝的 Edge。
身分卡片隨後顯示 Edge <version> (system install)。什麼都解析不到時,指令會印出安裝指引(npx extension install edge)並以代碼 1 結束。缺少 Edge 時不會有靜默的 Chromium 替代品。 如果一個 Chromium 視窗仍然讓你意外,請讀取 ready.json 的 binary。它會指出實際啟動的執行檔,binaryProvenance 會告訴你原因。請求的 chrome 或 chromium 可以借用受管理的家族執行檔(見上文),但請求的 edge 不行。輸出合約兩種情況都成立:只有當 edge 是請求的目標時,dist/edge 才會存在。

執行檔如何選定

從 4.1.39 之後的版本起,dev、start 與 preview 對每個瀏覽器都依同一個順序解析執行檔:
  1. 旗標:--chromium-binary 或 --gecko-binary。
  2. 該瀏覽器的環境變數。
  3. 來自 npx extension install <browser> 的受管理執行檔。
  4. 系統安裝。
變數和旗標一樣,是你做出的選擇。變數指向不存在的路徑或無法執行的檔案時,啟動會以 E_BROWSER_BINARY_INVALID 失敗。執行絕不會略過它去走下一步。 請求 chrome 時仍然會拒絕品牌版的系統 Chrome。指向品牌版 Chrome 的變數不會被採用,執行會繼續使用受管理的執行檔。 對 Firefox 來說,受管理這一步會優先選擇穩定版。同一個快取裡的 nightly 只有在沒有穩定版時才會執行,這時卡片會顯示 Firefox Nightly。

執行檔來源標籤

ready.json 用 binaryProvenance 記錄這次工作階段的執行檔來自哪裡: 身分卡片上沒有 Binary 列。它的 Browser 列只為你能處理的兩種情況加上標註:
(pinned with <旗標或變數>) 寫明是什麼選定了執行檔。當執行檔來自你的系統時,chrome、chromium、edge 與 firefox 會印出 (system install)。受管理的執行檔與具名分支沒有任何標註。

Chromium 快照 vs 穩定版

受管理的 chromium 安裝是主線(tip-of-tree)快照,而不是穩定版釋出。當系統上存在穩定版 Chromium 時,Extension.js 會自動切換過去,並印出一則帶有退出方式的警告。設定 EXTENSION_PREFER_CHROMIUM_SNAPSHOT=true 就會繼續使用快取的快照。 在 Chromium 系列內部,這種替換是安全的:dist/chrome 與 dist/chromium 逐位元組相同,因為 manifest 前綴是依引擎系列解析,而不是依廠商。前綴規則請參見瀏覽器專屬的 manifest 欄位。 若要預先安裝受管理的執行檔以取得可重現的執行結果,請使用 npx extension install <browser> 或 npx extension install all(後者也涵蓋 chromium)。

支援的瀏覽器

具名瀏覽器目標: 具名分支(從你的系統自動定位,不需要執行檔路徑): 如果具名分支未安裝,Extension.js 會以安裝指引結束。請參見 執行其他瀏覽器。 引擎類型目標(需自訂執行檔): Extension.js 在內部把 firefox-based 視為 Gecko 引擎目標。

引擎目標的用途

chromium-based 與 gecko-based 針對的是一個引擎家族,而不是單一廠商。 在 dev、start 與 preview 中,它們用來執行一個沒有具名目標的執行檔。想像一個 nightly 分支、公司內部建置,或內建定位器不認識的分支。 在 build 中,它們是為了散布而存在,完全不涉及執行檔:
  • extension build --browser=chromium-based 會把家族通用的產物寫到 dist/chromium-based。
  • 該產物會解析 chromium: manifest 前綴、讀取 .env.chromium-based,並設定 EXTENSION_BROWSER=chromium-based。
  • 把這一個套件發佈給 Chrome、Brave、Edge 或任何其他 Chromium 分支上的使用者。
當商店建置需要廠商專屬的 manifest 欄位時,選擇具名目標(chrome、edge)。當一份產物要服務整個家族時,選擇引擎目標。參見引擎目標對 build 的意義。

Safari 與其他 WebKit 目標

除了 Chromium 系列與 Firefox(Gecko 引擎),Extension.js 也能在 macOS 上把你的擴充功能建置成 Safari 應用程式。 Safari 是開發與建置目標:支援 build 與 dev,不支援 preview 與 start。dev 會轉換你的擴充功能、簽章並開啟一個 app、串流記錄,並在你於 Safari 設定中啟用一次擴充功能之後,每次儲存都重新載入。它需要 macOS 與完整的 Xcode 應用程式。完整流程、需求,以及如何在 Safari 中啟用該擴充功能,請參見 建置 Safari 擴充功能。

多瀏覽器選擇

你可以在一個指令中執行多個具名瀏覽器:
使用逗號分隔的值即可依序執行多個具名目標(例如 --browser=chrome,edge,firefox)。

限制與行為

  • 在會啟動瀏覽器的指令(dev、start、preview)中,chromium-based 需要 --chromium-binary;build 不需要執行檔。
  • gecko-based / firefox-based 在同樣前提下需要 --gecko-binary。
  • 引擎類型目標會路由到同樣的 Chromium/Firefox 啟動器,但行為會依引擎調整。
  • 作為 build 目標時,引擎目標擁有獨立的 dist/<target> 目錄、.env.<target> 解析、EXTENSION_BROWSER 值與 manifest 前綴——見引擎目標對 build 的意義。

Firefox 建置會對僅 Chromium 可用的 API 發出警告

從 4.1.18 開始,針對 Gecko 目標的正式建置會掃描輸出的 bundle,尋找兩種會被 addons-linter 回報為 UNSUPPORTED_API 的呼叫:任何 manifest 版本上的 chrome.sidePanel.*,以及 Manifest V2 上的 chrome.action.*。每次命中都會印出一則點名檔案的警告。建置仍然成功。
修正方式是一個由打包工具在建置時解析的分支,這樣 Firefox 的 bundle 會把這個呼叫整個去掉:
在 4.1.39 及更早的版本裡,像 chrome.sidePanel?.setPanelBehavior() 這樣的執行期防護仍然會觸發警告。 從 4.1.39 之後的版本起,Firefox 永遠執行不到的呼叫不會觸發警告。這包括位於 if (chrome.sidePanel) 之後的呼叫、寫成 chrome.sidePanel?.setPanelBehavior() 的呼叫,以及位於 typeof chrome.sidePanel !== "undefined" 檢查之後的呼叫。Safari 的警告辨識同樣的防護,見 Safari。 執行期防護只能讓建置警告安靜下來。addons-linter 比對的是對命名空間的靜態讀取,而不是實際執行的程式碼。只有基於 import.meta.env.EXTENSION_PUBLIC_BROWSER 的建置時分支才會把這個呼叫從 Firefox 的 bundle 裡去掉,而這正是消除商店檢查裡 UNSUPPORTED_API 發現的方法。各目標上 EXTENSION_PUBLIC_BROWSER 的值見環境變數。

最佳實務

  • 日常迭代用具名瀏覽器:chrome、edge 與 firefox 是日常測試最快的路徑。
  • 有意識地使用引擎類型模式:在驗證自訂執行檔或需要家族通用建置時使用 chromium-based / gecko-based。
  • 每個瀏覽器保持設定檔隔離:除錯時減少跨瀏覽器的狀態洩漏。
  • 搭配瀏覽器專屬欄位:用瀏覽器前綴的 manifest 鍵表達真正不同的行為。

後續步驟