跳轉到主要內容
為一個或多個瀏覽器目標產生正式版擴充功能產物。 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 專案則會跳過這個步驟。
範例輸出結構:
從 4.1.41 之後的版本開始,透過符號連結存取的專案,建置出的位元組與用真實路徑建置的相同。印出的路徑保留你輸入的路徑,而 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 檔:
這些 map 從不進入 ZIP 檔。它們留在 dist/<browser> 裡供你使用,所以你可以讀懂已發佈建置拋出的堆疊。在 extension.config.js 裡設定 commands.build.sourceMaps: true,每次建置都會寫出它們。預設值是 false。

範例

使用 zip 輸出與自訂檔名建置

此範例的建置會以 Edge 與 Chrome 為目標,並將兩個輸出壓縮成 zip。壓縮檔會儲存為 dist/my-extension-edge.zip 與 dist/my-extension-chrome.zip,因為每個發佈壓縮檔都會附加瀏覽器名稱,即使只建置一個目標也一樣。

帶有 polyfill 支援的建置

此範例的建置會以 Chrome 與 Firefox 為目標,並在合適情境下包含 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.
從 4.1.41 之後的版本起:
  • 警告字串以 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 的代碼、訊息與位置:
輸出最多印 20 條發現,linter 最多執行 10 秒。超過 20 條時,會有一行說明還有多少條沒顯示,並指向 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 並略過檢查:
安裝指令會依你專案使用的套件管理器來措辭。 從 4.1.41 之後的版本起,已安裝但無法載入的 linter 會有自己的一行。它會點名該副本與原因,並建議重新安裝,而不是 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: 開頭的一行裡印出同樣的修正方法。同一個檔案不會在兩種行裡都被回報:
這個上限是 Gecko 目標預設 optimization.splitChunks 的一部分。可以在 config hook 裡修改它,見 Rspack 設定。

面向 Opera Add-ons 的可讀輸出

Opera 的審核標準要求審核者能讀懂程式碼:擴充功能自身的程式碼若被壓縮或混淆會被拒絕,第三方函式庫則可以保持壓縮。因此正式模式下的 extension build --browser=opera 不做壓縮,並印出一行提示:
建置會對整個產物關閉壓縮,包括相依套件在內,因為一個打包後的 chunk 可能把你的程式碼和相依套件的程式碼混在一起。傳入 --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。

後續步驟