跳轉到主要內容
Extension.js 預設以瀏覽器執行期為目標,不會自動為 Node 核心模組加上 polyfill,以維持較小的 bundle 體積。如果相依套件用到 buffer、stream 或 crypto,建置時你會看到解析錯誤。下面說明何時該加入 polyfill,又何時該改用瀏覽器原生方案。

什麼情況下適合加入 Node polyfill

  • 必要的相依套件在瀏覽器執行期中需要 Node 核心模組。
  • 你正在從以 Node 為主的套件逐步遷移程式碼。
  • 你可以為了特定執行期能力,接受較大的 bundle 體積。

範本範例

new-typescript

new-typescript template screenshot 當你的擴充功能需要明確調整打包工具或 polyfill 時,從 TypeScript 基線開始。
Repository: extension-js/templates/newtab-typescript

content-typescript

content-typescript template screenshot 當依賴 Node 的函式庫會在頁面注入流程中執行時,採用 content script 的 TypeScript 基線。
Repository: extension-js/templates/content-typescript

new-crypto

new-crypto template screenshot 看 Web Crypto API(window.crypto.subtle)如何在 new-tab 擴充功能中直接使用,不需要任何 polyfill。
Repository: extension-js/templates/newtab-crypto

預設行為

  • 建置目標以瀏覽器為主(web)。
  • 模組解析優先採用瀏覽器匯出(browser、module、main)。
  • crypto、path 與 fs 會被對應成 false,因此它們會解析到一個空模組。建置會成功, 而匯入則改為在執行階段失敗(例如 path.join 是 undefined)。
  • 其餘所有 Node 核心模組,包含 buffer、stream、os 以及帶 node: 前綴的指定符, 都沒有 fallback,會以 Module not found: Can't resolve 讓建置失敗。
所以缺少的 Node API 會出現在兩個地方之一,是哪一個取決於該模組。 用下面的明確 fallback 來處理這兩種情況。

node: 指定符與建置錯誤

從 4.1.39 之後的版本起,node:fs 和 fs 是同一個請求,所以兩種寫法得到同樣的結果:
  • crypto、fs 與 path 無論哪種寫法都會解析到一個空模組,fs/promises 這樣的子路徑也一樣。
  • 其他任何內建模組都會讓建置停下。訊息會寫明這個內建模組、匯入它的檔案,以及要設定的 resolve.fallback 鍵。
  • 對沒有替身的內建模組呼叫 require() 只是一則警告。這個呼叫會原樣留在輸出裡,只有那條程式碼路徑真的執行時才會拋錯。設定 EXTENSION_STRICT_REFS=true 可以讓它使建置失敗。
在 4.1.39 及更早的版本裡,帶 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 鍵與它的裸名相同。在更早的版本裡,它會讓建置失敗。

下一步

影片導覽