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 專案則會跳過這個步驟。ready.json 記錄真實路徑。
在 dev 工作階段旁邊建置
extension dev 與 extension build 都會寫入 dist/<browser>。當同一個瀏覽器的 dev 工作階段正在執行時,往該資料夾建置會被拒絕,並回報 E_DEV_SESSION_DIST_SHARED,不會寫入任何東西。訊息會列出該工作階段的 process id,並指向 --out-dir。
要在 dev 視窗保持開啟的同時測試或打包一份正式建置,請傳入 --out-dir。建置會寫到 <path>/<browser>,並把 zip 放在 <path>/:
build/chrome 與 build/<name>-<version>-chrome.zip,而 dist/chrome 維持 dev 工作階段留下的狀態。同樣的設定也能寫進 extension.config.js 的 commands.build.outDir。
瀏覽器目標矩陣
引擎目標對 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:鍵會作為該目標最具體的匹配生效,疊加在家族層級的chromium:鍵之上。chrome:與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。
development 模式的建置是可以直接發布的。它保留你在 manifest 中寫的 CSP 與權限,不注入任何 reload 用戶端,它的 zip 也不包含 source map(.map 檔會留在 dist/<browser> 供你使用)。只有 extension dev 會開啟 dev 檢測。--zip 在任何模式下都會打包輸出,不只在 production。
Zip 行為
每個 zip 都落在
dist/ 裡,與 dist/<browser> 資料夾並列而不是放在它裡面,因為 dist/<browser> 是商店上傳或 load-unpacked 整個取走的資料夾。沒有 --zip-filename 時,名稱是 manifest 的 name 轉小寫、移除 a-z0-9 與空白以外的所有字元、把剩下的空白換成連字號,再接上 manifest 的 version 與瀏覽器。一個名為 My Extension+、版本為 1.0.0 的 manifest 會打包成 dist/my-extension-1.0.0-chrome.zip。因為名稱經過改寫,請從建置輸出讀取實際路徑,而不要用 manifest 名稱自行組合。在 --output json 下,每個壓縮檔都會列在 zip_artifacts 裡,附上路徑與大小。
--zip-filename 同時命名兩個壓縮檔,而且發佈壓縮檔一定會附加瀏覽器名稱,所以在不同次執行裡用同一個名稱建置兩個瀏覽器時,彼此不會互相覆寫。在 Chrome 建置裡傳入 --zip-filename=review-bundle.zip 與 --zip-source 會寫出 dist/review-bundle-chrome.zip 與 dist/review-bundle-source.zip。原始碼壓縮檔對每個瀏覽器都一樣,所以它的名稱不帶瀏覽器,一次建置只寫一個原始碼壓縮檔。已經以瀏覽器名稱結尾的名稱會保持原樣。--browser=edge,chrome --zip-filename=my-extension.zip 會寫出 dist/my-extension-edge.zip 與 dist/my-extension-chrome.zip。
從 4.1.39 之後的版本起,--zip-dir <path> 決定 ZIP 檔寫到哪個資料夾。路徑相對於專案根目錄,也可以是絕對路徑。--zip-dir release 會寫出 release/my-extension-1.0.0-chrome.zip,原始碼壓縮檔也落在同一個資料夾裡。同樣的設定可以寫進 extension.config.js,鍵是 commands.build.zipDir。
有兩種路徑會讓建置報錯並停止。一種是離開專案的相對路徑,例如 ../release。要寫到專案之外,請傳絕對路徑。另一種是 dist/<browser> 裡面的資料夾,因為那個資料夾是整個發佈出去的。
--zip-filename 只決定名稱。值裡帶的資料夾會被去掉,所以在 Chrome 建置裡傳 --zip-filename=out/review.zip,檔名是 review-chrome.zip。
從 4.2.0 之後的版本起,編譯失敗時不會建立 ZIP 檔案,因為 dist/<browser> 裡仍是上一次的建置。ZIP 檔案無法寫入時,建置以 E_ZIP_SKIPPED 失敗,結尾的 Build failed with 1 error. 會補充說明輸出資料夾已就位,可以照建置結果載入。
正式建置的 source map
正式建置不寫 source map。從 4.1.39 之後的版本起,--source-maps 會在 dist/<browser> 裡的每個腳本與樣式表旁邊寫出一個 .map 檔:
dist/<browser> 裡供你使用,所以你可以讀懂已發佈建置拋出的堆疊。在 extension.config.js 裡設定 commands.build.sourceMaps: true,每次建置都會寫出它們。預設值是 false。
範例
使用 zip 輸出與自訂檔名建置
dist/my-extension-edge.zip 與 dist/my-extension-chrome.zip,因為每個發佈壓縮檔都會附加瀏覽器名稱,即使只建置一個目標也一樣。
帶有 polyfill 支援的建置
同時建置原始碼與產物 zip
成功的建置會印出什麼
在資源摘要之後,一次成功的建置會印出輸出資料夾與它的大小。 正式建置接著會印出產出它的 Node.js、套件管理器與 Extension.js 版本, 讓商店審查人員可以重新建置這個套件並得到相同的位元組:pnpm build)啟動時,版本行中才會出現套件管理器。
從 4.1.39 之後的版本起,那一行裡的大小只計算發佈出去的檔案。source map 另外計算,那一行會說明有多少沒有進入 ZIP 檔:
compiled with 1 warning in 316 ms, listed below.,而不是 compiled in。
4.2.0 之前的版本印出 compiled with warnings,所以比對那段文字的腳本必須改為比對計數的形式。
從 4.1.41 之後的版本起,在外掛的 done hook 中失敗的建置不會印出 compiled in 那一行。
從 4.2.0 之後的版本開始,失敗的建置也會印出警告詳情,和成功的建置一樣。4.2.0 及之前的版本只在設定 EXTENSION_VERBOSE=1 時才印出失敗建置的警告。
從 4.1.39 之後的版本起,如果一個檔案被多個 entry 匯入,它產生的警告或錯誤只印出一次,也只計數一次。
當輸出不是終端機,或是設定了 NO_COLOR 時,打包工具的錯誤與警告也會以純文字印出,build 與 dev 都是如此。FORCE_COLOR=1 保留顏色,FORCE_COLOR=0 關閉顏色。
不要用這些文字為 CI 把關。它是寫給人看的,會隨版本改變。
請改用結束碼,或下面的 --output json,那才是受支援的機器契約。
用 --output json 取得機器可讀輸出
--output json 會在 stdout 印出一個 schema-1 信封,並把給人看的建置訊息導到 stderr。stdout 始終可以當作單一份 JSON 文件解析。
- 成功的執行會印出一個
status: "built"框。它的value帶著建置出的瀏覽器、解析後的模式,以及每個瀏覽器一份摘要。每份摘要記錄輸出路徑、資源總量、警告文字,以及相關時的 Safari 應用程式識別。當能解析出錯誤碼時,每個警告字串都以W_CODE:開頭,例如W_CSS_DEAD_REF: ...,與logs和uninstall的慣例相同。 - 失敗的建置會在行程以
1結束前印出一個ok: false框,其status: "build-failed"。編譯錯誤帶error.code: "E_COMPILE",並且error.details會列出失敗背後的每條診斷,各自帶有錯誤碼、檔案和位置,錯誤排在前面,上限 20 條,截斷時設定truncated: true。見編譯診斷。專案資料夾不存在帶E_PROJECT_NOT_FOUND,資料夾裡沒有 manifest 帶E_MANIFEST_NOT_FOUND,manifest 無法解析帶E_MANIFEST_INVALID。設定檔載入失敗帶E_CONFIG_LOAD。 - 路徑引數是遠端 URL 時,下載進度行同樣寫到 stderr。回傳的不是 ZIP 封存檔、封存檔已損毀或含有位於其資料夾之外的條目帶
E_REMOTE_ZIP_INVALID,逾時帶E_REMOTE_FETCH_TIMEOUT,連線遭拒或 HTTP 錯誤帶E_REMOTE_DOWNLOAD。含有位於其資料夾之外的條目的封存檔會在寫入任何內容之前遭拒,訊息會點名該條目。 - 從 4.2.0 之後的版本起,被
SIGINT或SIGTERM停止的建置會印出一個帶E_INTERRUPTED與value.signal的stopped影格,並以130或143結束。上一次建置的輸出保持原樣。文字模式下,建置以同樣的結束代碼結束,並且不在 stdout 上印出任何內容。 - 從 4.2.0 之後的版本起,一旦
build印出擴充功能已建置完成,Ctrl+C或SIGTERM就不再停止它。執行以結束代碼0結束,--output json執行以它自己的建置完成影格結束。當--browser列出多個瀏覽器時,這從最後一個瀏覽器的那一行起成立。在那一行之前的訊號仍然以130或143結束,並保留之前的輸出。 在--output json之外,它還會印出一行:The build had already finished, so there was nothing to stop.
- 警告字串以
W_*代碼開頭。較早的版本使用E_*名稱。 - 在建立編譯器時拋出例外的外掛,例如在它的
apply中,帶E_COMPILE_FATAL。 - 以空白訊息拋出的錯誤會點名它來自的檔案、行與欄。
- 建置還在尋找專案與其瀏覽器時的拒絕不會在 stderr 上印出任何內容。
- 之後的每個失敗也會在 stderr 上印出給人看的文字。
- 失敗建置的框架會像成功建置一樣,在
warnings中列出建置遇到的帶代碼的警告,每個一次。
dist/extension-js/<browser>/build-summary.json。以 shell 呼叫 extension build 的指令碼可以從那裡讀取結構化的警告。請檢查檔案的修改時間,以免讀到過期檔案。
從 4.1.39 之後的版本起,每份摘要裡的 total_assets、total_bytes 與 largest_asset_bytes 只計算發佈出去的檔案。寫出了 source map 的建置會用 source_map_assets 與 source_map_bytes 另外回報它們。沒有寫出 source map 的建置不帶這兩個欄位。
Firefox 建置的商店檢查
從 4.1.18 開始,針對 Gecko 目標(firefox、gecko-based 以及各 Gecko 分支)的正式建置會在專案裡裝有 addons-linter 時,用它檢查 dist/<browser>。這個 linter 正是 addons.mozilla.org 審核提交時執行的工具,所以這項檢查能在你上傳之前揭露會被拒絕的問題。
每一條發現都以警告印出。建置永遠不會因此失敗,結束碼保持為 0。先印一行摘要,然後每條發現各佔一行,帶著 linter 的代碼、訊息與位置:
npx addons-linter dist/firefox 查看完整報告。執行超過 10 秒的 linter 會被放棄,建置在沒有這項檢查的情況下繼續。
落在打包了相依套件的 chunk 裡的發現會標注歸屬,因為單看檔名可能指向錯誤的作者。當該 chunk 裡沒有你自己的程式碼時,這一行以 - this file is bundled dependency code (react, react-dom), not yours 結尾。當該 chunk 兩者混合時,以 - this file also bundles react, react-dom, so the finding may be theirs 結尾。
當沒有安裝 addons-linter 時,建置會為每個專案印一行 info 並略過檢查:
npx addons-linter,因為後者會執行同一個損壞的副本。
當發現的問題落在打包進來的套件裡時,檢查會在瀏覽器資料夾旁寫出 amo-reviewer-note.md,例如 dist/amo-reviewer-note.md。把其中打包函式庫的段落貼進提交內容。從 4.1.41 之後的版本起,lint 沒有完成的建置會把上一份說明移到 amo-reviewer-note.stale.md。找不到 linter 的建置也一樣,並由那一行說明。
用 --no-addon-lint,或在 extension.config.js 中設定 commands.build.addonLint: false,即可關閉檢查。非正式模式會略過它,因為開發產物帶有僅供開發的授權,linter 會白白地標記它們。extension start 也會略過它,因為 start 是預覽建置,而不是出貨建置。
Firefox 建置會拆分大檔案
addons.mozilla.org 不解析 5 MB 以上的腳本,商店檢查遇到這樣的檔案就會失敗。從 4.1.39 之後的版本起,針對 Gecko 目標的建置會把它能拆分的檔案限制在 4 MB 原始碼以內。Chrome、Edge 與 Safari 的輸出不變。
頁面會在自己的 HTML 裡列出每個部分,所以被拆分的頁面不需要你做任何更動。針對 Firefox 建置時,不要在自己的程式碼裡寫死
action/index.js 或 shared/commons.js。
對於超過限制的單檔腳本,商店檢查會回報 FILE_TOO_LARGE,這一行的結尾給出修正方法:用動態 import() 載入那個大型相依套件,讓它作為低於限制的獨立檔案輸出。如果沒有安裝 addons-linter、它沒有給出結果,或者你用 --no-addon-lint 或 commands.build.addonLint: false 關閉了檢查,建置會在以 Firefox build: 開頭的一行裡印出同樣的修正方法。同一個檔案不會在兩種行裡都被回報:
optimization.splitChunks 的一部分。可以在 config hook 裡修改它,見 Rspack 設定。
面向 Opera Add-ons 的可讀輸出
Opera 的審核標準要求審核者能讀懂程式碼:擴充功能自身的程式碼若被壓縮或混淆會被拒絕,第三方函式庫則可以保持壓縮。因此正式模式下的extension build --browser=opera 不做壓縮,並印出一行提示:
--minify 可以覆寫這個預設值,也可以在 extension.config.js 中設定 commands.build.minify。同一個選項對其他目標反向生效:當審核者要求時,--no-minify 會讓 Chrome 或 Firefox 建置保持可讀。
最佳實務
- 檢視建置記錄: 每次建置後檢查警告與遺漏的資源。
- 最佳化 manifest: 讓
manifest.json與每個目標瀏覽器相容。 - 有意義地命名產物: 使用
--zip-filename讓 CI 產物有穩定名稱。 - 驗證每個目標輸出: 在發布前檢查各個
dist/<browser>資料夾。之後的一次dev會用帶開發檢測的建置覆寫同一個資料夾,那個建置會加上scripting、tabs、management、storage等權限,把你的 content script 的比對模式合併進host_permissions,並把hot/*與extension-js-control.json列為只對這些比對開放的 web-accessible resources。沒有 content script 的專案不會得到後兩項。打包或發布前請重新執行一次build。
後續步驟
- 把這個建置透過一個連結交給別人審閱,參見 Share an unpublished build for review。
- 把產物提交到瀏覽器商店,參見 extension.dev 發布文件。
- 用
publish為專案在 extension.dev 上取得可分享的 URL。 - 用
preview執行現有的建置輸出。 - 用
start在一個指令中完成建置與啟動。 - 在
extension.config.js中集中設定共用預設值。 - 在 環境變數 中了解設定的環境檔載入行為。
- 在 可用的瀏覽器 中查看支援的目標。

