跳轉到主要內容
在不離開 Extension.js 工作流程的前提下自訂打包行為。 不必分叉預設設定就能解決自訂 bundler 需求。可以直接加上 loader(檔案型態轉換)、plugin(建置時擴充)與別名(import 捷徑)。Extension.js 使用 Rspack(基於 Rust 的 JavaScript bundler,@rspack/core)建置,你可以直接擴充產生出的設定。

運作方式

在專案根目錄建立下列其中一個檔案:
  • extension.config.js
  • extension.config.mjs
  • extension.config.cjs
使用 config 鍵來修補產生出的 bundler 設定。

config 能力

選項一:函式 hook(建議)

選項二:物件合併

config 也可以是物件,Extension.js 會把它合併進基底設定。

Rspack 優先,相容 webpack

Extension.js 原生使用 Rspack,但你仍可使用大部分 webpack 生態系。
  • 設定型別擴充自 @rspack/core 的 Configuration。
  • 許多 webpack loader/plugin 透過相容層可運作。
  • 部分 webpack 內部/plugin 與 Rspack 並非完全 1:1 相容。
使用 Rspack 原生 plugin 的範例。從 4.1.39 之後的版本起,hook 的第二個引數帶有 rspack,也就是 Extension.js 用來編譯的 bundler。從它上面取 plugin 類別,你的專案就不需要自己安裝 @rspack/core:
在 4.1.39 及更早的版本裡,請從 @rspack/core 匯入這個類別。這個引數的全部欄位見 hook 上下文,resolve.fallback 的做法見在瀏覽器擴充功能中使用 Node API。

診斷訊息裡的 bundler 名稱

bundler 自己的文字寫 Rspack 的地方,建置輸出會寫成 Extension.js,因為你執行的工具是 Extension.js。從 4.1.39 之後的版本起,需要你親手輸入的名稱會保持原樣。這包括反引號裡的文字、帶引號的鍵 "rspack"、解構寫法 {rspack},以及 rspack.ProvidePlugin 這樣的成員。診斷訊息裡像 new rspack.NormalModuleReplacementPlugin(...) 這樣的一行,可以照著印出的內容直接貼上。

在多個 entry 之間共享模組

Extension.js 只拆分 HTML 頁面。預設的 optimization.splitChunks 會給頁面兩個穩定的同級檔案:shared/framework.js 存放 UI 框架的執行階段,shared/commons.js 存放被兩個或更多頁面匯入的任何模組。框架群組涵蓋 React、Preact、Vue、Svelte 與 Lit。這兩個名稱都不帶雜湊,所以 manifest 項目或公開資源可以一直指向它們。 從 4.1.39 之後的版本起,Firefox 建置會把超過 4 MB 的共享檔案輸出成帶編號的幾個部分,例如 shared/commons-0.js。見 Firefox 建置會拆分大檔案。 其他每個介面都只保留一個檔案。manifest 為 background worker、content script 或注入腳本各指定一個腳本,這些介面永遠不會載入同級檔案。 這就是為什麼在頁面與 content script 之間共享模組仍然需要 import()。Rspack 會為它輸出一個 chunk,每個呼叫方按需從擴充功能自身的 origin 取得這個 chunk。cacheGroup 可以給這個 chunk 一個穩定的名稱:
這樣設定後,從彈出視窗和選項頁分別執行 await import("../shared/big") 都會解析到同一個輸出檔 shared.js。請把 chunks 保持為 "async"。同步拆分會把程式碼移出 entry 檔案,但輸出的 HTML 和 manifest 只引用該 entry 檔案,頁面永遠不會載入被拆出的 chunk。service worker 會保留自己的一份模組副本,因為它在安裝之後無法再擷取 chunk。content script 也可以共享這個 chunk,但必須透過 web_accessible_resources 公開該檔案,並透過 chrome.runtime.getURL 匯入。這兩條規則請見延遲載入。

何時使用

  • 為專案特定的檔案型態加入自訂 loader/規則。
  • 加入用於編譯時轉換與診斷的 plugin。
  • 覆寫 Extension.js 一級選項未提供的解析別名與模組行為。

最佳實務

  • 優先使用一級選項:先嘗試 browser / commands 設定鍵,再考慮底層 bundler 覆寫。
  • 最小化修補:只更動需要的部分,然後回傳設定。
  • plugin 保持 Rspack 友善:可用 Rspack 原生 plugin 時優先使用。
  • 在所有目標驗證:設定變更後,針對你的瀏覽器矩陣測試 dev、start、preview 與 build。

下一步