@rspack/core)建置,你可以直接擴充產生出的設定。
運作方式
在專案根目錄建立下列其中一個檔案:extension.config.jsextension.config.mjsextension.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,也就是 Extension.js 用來編譯的 bundler。從它上面取 plugin 類別,你的專案就不需要自己安裝 @rspack/core:
@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。
下一步
- 進一步了解 extension 設定(
extension.config.js)。 - 進一步了解 多平台建置。

