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

​
選擇合適的目標

​
運作方式

在 dev、start、preview 與 build 中使用 --browser 來選擇目標。 如果沒指定瀏覽器,CLI 預設使用 chromium。 --browser 只接受下列這些值,可以單獨使用,也可以用逗號分隔:
--browser=all 也會被接受,它會展開為 chrome, edge, firefox。
開發時請優先使用 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 擴充功能。

​
請求的目標 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。這則警告刻意不寫出替代執行檔的路徑。工作階段的身分卡片已經有一列 Binary 指出實際使用的執行檔,所以這件事只會印一次。輸出資料夾與產出的 manifest 與沒有回退時完全相同。

​
沒有受管理 Edge 時 --browser=edge 會做什麼

edge 永遠不會換成另一個瀏覽器。Extension.js 依這個順序解析 Edge 執行檔:
  1. EDGE_BINARY 環境變數中的路徑(有設定時)。
  2. 來自 npx extension install edge 的受管理 Edge,或系統上已安裝的 Edge。
兩者都解析不到時,指令會印出安裝指引(npx extension install edge)並以代碼 1 結束。缺少 Edge 時不會有靜默的 Chromium 替代品。 如果一個 Chromium 視窗仍然讓你意外,檢查身分卡片。它的 Binary 列會指出實際啟動的執行檔,來源標籤會告訴你原因。請求的 chrome 或 chromium 可以借用受管理的家族執行檔(見上文),但請求的 edge 不行。輸出合約兩種情況都成立:只有當 edge 是請求的目標時,dist/edge 才會存在。

​
執行檔來源標籤

身分卡片會標示這次工作階段的執行檔來自哪裡:

​
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(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 的意義。

​
最佳實務

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

​
後續步驟