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 只對會啟動瀏覽器的指令有意義。
引數與旗標
--author 與 --author-mode 是 --debug 的隱藏、已淘汰別名。
Safari 旗標
這些旗標只適用於safari 與 webkit-based 目標。把其中任何一個和其他目標一起傳入都會以錯誤結束,所以打錯字時不會靜默地什麼都不做。
Safari 打包會在建置前先跑一次預檢。在非 macOS 主機上,
build 會警告並跳過 Safari 打包步驟,但仍會編譯 bundle。在 macOS 上,若 Xcode 損壞或缺少,則屬致命錯誤。
共用全域選項
也支援 全域旗標。模式覆寫
--mode 會覆寫此次建置的打包工具模式與 NODE_ENV。接受 development、production 或 none。當你需要在 staging 或除錯場景使用非正式版打包時,可用它對齊 Vite/webpack 的工作流程。
production。
Zip 行為
每個 zip 都落在它自己的
dist/<browser> 資料夾裡,與未壓縮的輸出放在一起。沒有 --zip-filename 時,名稱是 manifest 的 name 轉小寫、移除 a-z0-9 與空白以外的所有字元、把剩下的空白換成連字號,再接上 manifest 的 version。一個名為 My Extension+、版本為 1.0.0 的 manifest 會打包成 dist/chrome/my-extension-1.0.0.zip。因為名稱經過改寫,請從建置輸出讀取實際路徑,而不要用 manifest 名稱自行組合。
範例
使用 zip 輸出與自訂檔名建置
my-extension.zip。
帶有 polyfill 支援的建置
同時建置原始碼與產物 zip
成功的建置會印出什麼
在資源摘要之後,一次成功的建置會印出輸出資料夾與它的大小, 接著是一個可以把建置交給別人審閱的連結:compiled with warnings 而不是 compiled in。
不要用這些文字為 CI 把關。它是寫給人看的,會隨版本改變。
請改用結束碼,或下面的 --output json,那才是受支援的機器契約。
用 --output json 取得機器可讀輸出
--output json 會在 stdout 印出一個 schema-1 信封,並把給人看的建置訊息導到 stderr。stdout 始終可以當作單一份 JSON 文件解析。
- 成功的執行會印出一個
status: "built"框。它的value帶著建置出的瀏覽器、解析後的模式,以及每個瀏覽器一份摘要。每份摘要記錄輸出路徑、資源總量、警告文字,以及相關時的 Safari 應用程式識別。 - 失敗的建置會在行程以
1結束前印出一個ok: false框,其status: "build-failed"、error.code: "E_COMPILE"。
dist/extension-js/<browser>/build-summary.json。以 shell 呼叫 extension build 的指令碼可以從那裡讀取結構化的警告。請檢查檔案的修改時間,以免讀到過期檔案。
最佳實務
- 檢視建置記錄: 每次建置後檢查警告與遺漏的資源。
- 最佳化 manifest: 讓
manifest.json與每個目標瀏覽器相容。 - 有意義地命名產物: 使用
--zip-filename讓 CI 產物有穩定名稱。 - 驗證每個目標輸出: 在發布前檢查各個
dist/<browser>資料夾。之後的一次dev會用帶開發檢測的建置覆寫同一個資料夾,那個建置會加上scripting、tabs、management、storage等權限,以及針對<all_urls>的host_permissions和寬鬆的 web-accessible resources。打包或發布前請重新執行一次build。
後續步驟
- 把這個建置透過一個連結交給別人審閱，參見 Share an unpublished build for review。
- 把產物提交到瀏覽器商店，參見 extension.dev 發布文件。
- 用
publish為專案在 extension.dev 上取得可分享的 URL。 - 用
preview執行現有的建置輸出。 - 用
start在一個指令中完成建置與啟動。 - 在
extension.config.js中集中設定共用預設值。 - 在 環境變數 中了解設定的環境檔載入行為。
- 在 可用的瀏覽器 中查看支援的目標。