build 會以 production 模式編譯你的擴充功能,並把輸出寫入 dist/<browser>。
針對 monorepo/submodule 專案,請參見 環境變數 中的設定階段環境變數解析(先尋找專案根目錄,再退回到 workspace 根目錄)。
何時使用 build
- 為 Chrome Web Store、Edge Add-ons 或 Firefox Add-ons 準備擴充功能套件。
- 在持續整合(CI)工作中產生可重現的正式版產物。
- 在送審前驗證正式版打包輸出,以及各瀏覽器目標之間的差異。
Build 指令功能
用法
Build 輸出
執行build 後,Extension.js 會為所選的瀏覽器目標產生最佳化檔案。輸出會放到 dist/,每個目標一個子資料夾。每個資料夾包含打包後的 JavaScript、CSS、HTML 與所需的執行階段資源。
對 TypeScript 專案,
build 也會重新產生 extension-env.d.ts 全域型別宣告(與
dev 產生的同一份檔案), 讓 CI 上的 tsc --noEmit
不論先前是否跑過 dev 都能順利通過。 純 JavaScript 專案則會跳過這個步驟。瀏覽器目標矩陣
引擎目標對 build 的意義
build 不會啟動瀏覽器，因此引擎目標在這裡並不指向某個執行檔——但它們仍會產出一個獨立的產物，而不是具名目標建置的改名副本：
- 獨立的輸出目錄。
--browser=chromium-based輸出到dist/chromium-based，與dev、preview、start在該目標下使用的目錄一致——以自訂 Chromium 執行檔開發的專案，建置產物路徑完全對應。 - 獨立的 env 解析。
.env.chromium-based與.env.chromium-based.production優先於家族層級的.env.chromium/.env.chrome/.env.edge，且打包後的程式碼中EXTENSION_BROWSER === "chromium-based"——程式碼與設定可以據此區分「通用 Chromium」與特定商店建置。 - 獨立的 manifest 前綴。
manifest.json中的chromium-based:鍵會作為該目標最具體的匹配生效，疊加在家族層級的chrome:/chromium:/edge:鍵之上。
gecko-based 相對 firefox 的行為完全相同。建置不需要瀏覽器執行檔——--chromium-binary/--gecko-binary 只對會啟動瀏覽器的指令有意義。
引數與旗標
共用全域選項
也支援 全域旗標。模式覆寫
--mode 會覆寫此次建置的打包工具模式與 NODE_ENV。接受 development、production 或 none。當你需要在 staging 或除錯場景使用非正式版打包時,可用它對齊 Vite/webpack 的工作流程。
production。
Zip 行為
範例
使用 zip 輸出與自訂檔名建置
my-extension.zip。
帶有 polyfill 支援的建置
同時建置原始碼與產物 zip
最佳實務
- 檢視建置記錄: 每次建置後檢查警告與遺漏的資源。
- 最佳化 manifest: 讓
manifest.json與每個目標瀏覽器相容。 - 有意義地命名產物: 使用
--zip-filename讓 CI 產物有穩定名稱。 - 驗證每個目標輸出: 在發布前檢查各個
dist/<browser>資料夾。
後續步驟
- 用
@extension.dev/deploy(npx @extension.dev/deploy)把產物發布到瀏覽器商店——建置成功後終端機也會印出這則提示。 - 用
preview執行現有的建置輸出。 - 用
start在一個指令中完成建置與啟動。 - 在
extension.config.js中集中設定共用預設值。 - 在 環境變數 中了解設定的環境檔載入行為。
- 在 可用的瀏覽器 中查看支援的目標。