buffer、stream 或 crypto,建置時你會看到解析錯誤。下面說明何時該加入 polyfill,又何時該改用瀏覽器原生方案。
什麼情況下適合加入 Node polyfill
- 必要的相依套件在瀏覽器執行期中需要 Node 核心模組。
- 你正在從以 Node 為主的套件逐步遷移程式碼。
- 你可以為了特定執行期能力,接受較大的 bundle 體積。
範本範例
new-typescript

content-typescript

new-crypto

window.crypto.subtle)如何在 new-tab 擴充功能中直接使用,不需要任何 polyfill。
預設行為
- 建置目標以瀏覽器為主(
web)。 - 模組解析優先採用瀏覽器匯出(
browser、module、main)。 crypto、path與fs會被對應成false,因此它們會解析到一個空模組。建置會成功, 而匯入則改為在執行階段失敗(例如path.join是 undefined)。- 其餘所有 Node 核心模組,包含
buffer、stream、os以及帶node:前綴的指定符, 都沒有 fallback,會以Module not found: Can't resolve讓建置失敗。
node: 指定符與建置錯誤
從 4.1.39 之後的版本起,node:fs 和 fs 是同一個請求,所以兩種寫法得到同樣的結果:
crypto、fs與path無論哪種寫法都會解析到一個空模組,fs/promises這樣的子路徑也一樣。- 其他任何內建模組都會讓建置停下。訊息會寫明這個內建模組、匯入它的檔案,以及要設定的
resolve.fallback鍵。 - 對沒有替身的內建模組呼叫
require()只是一則警告。這個呼叫會原樣留在輸出裡,只有那條程式碼路徑真的執行時才會拋錯。設定EXTENSION_STRICT_REFS=true可以讓它使建置失敗。
node: 前綴的指定符對每個模組都會讓建置失敗,crypto、fs 與 path 也不例外。
設定 Node polyfill
使用extension.config.js(或 .mjs / .cjs)擴充 Rspack 設定,並定義安全的 fallback。
一次只加一個 fallback
只需要一兩個模組時,不必用 polyfill plugin。安裝對應的瀏覽器套件,然後在config hook 裡擴充 resolve.fallback。把某個鍵設為 false 就得到一個空模組。Buffer 在 Node.js 裡是全域變數,所以用 ProvidePlugin 來提供它。
從 4.1.39 之後的版本起,hook 的第二個引數帶有 rspack,也就是 Extension.js 用來編譯的 bundler。從它上面取 plugin 類別,你的專案就不需要自己安裝 @rspack/core:
extension.config.js
resolve.fallback,這樣三個預設鍵會保留下來。require.resolve("buffer/") 結尾的斜線指向已安裝的套件,而不是 Node.js 的內建模組。
只以帶前綴的形式存在的名稱,例如 node:test,沒有 resolve.fallback 能對應到的裸鍵。請透過 rspack.NormalModuleReplacementPlugin 把它替換成你自己的模組:
extension.config.js
安裝選用的 polyfill 套件
擴充功能 API 與 Node API 的差別
在 CLI/設定中將polyfill 設為 true,會啟用 webextension-polyfill,這是一個讓早於 148 的 Chromium 瀏覽器(帶有 devtools_page 時為早於 152)可取用 browser.* API namespace 的相容層。更新的版本原生提供 browser。它不會啟用 Node 核心模組的 polyfill。
只有當函式庫無法在標準 Web API 下執行時,才使用 Node polyfill。
注意事項
- 不要假設擴充功能執行期可以存取檔案系統;除非你有明確的瀏覽器安全策略,否則請保持
fs: false。 - 盡量採用 Web Crypto(
crypto.subtle),而非引入體積較大的 Node crypto shim。 - Polyfill(Node API 的瀏覽器相容替代品)會增加 bundle 體積,可能影響擴充功能頁面與 content script 的啟動時間。
- 從 4.1.39 之後的版本起,
node:specifier 讀取的resolve.fallback鍵與它的裸名相同。在更早的版本裡,它會讓建置失敗。
下一步
- 了解如何自訂 Rspack 設定。
- 了解如何管理 Extension 設定。

