buffer、stream 或 crypto,构建时就会看到解析错误。下面会说明什么时候该加 polyfill,什么时候应选择浏览器原生的替代方案。
什么场景适合用 Node polyfill
- 必需的依赖在浏览器运行时里需要 Node 核心模块。
- 你正在把代码从以 Node 为中心的包逐步迁移过来。
- 为了得到某些运行时能力,你可以接受更大的包体积。
模板示例
new-typescript

content-typescript

new-crypto

window.crypto.subtle),不需要任何 polyfill。
默认行为
- 构建目标以浏览器优先(
web)。 - 模块解析优先选用浏览器导出(
browser、module、main)。 crypto、path和fs被映射为false,因此它们会解析到一个空模块。构建会成功, 但导入会在运行时失败(例如path.join是 undefined)。- 其他所有 Node 核心模块,包括
buffer、stream、os以及带node:前缀的说明符, 都没有回退,会以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 配置,并定义安全的回退。
一次只加一个回退
只需要一两个模块时,不必用 polyfill 插件。安装对应的浏览器包,然后在config 钩子里扩展 resolve.fallback。把某个键设为 false 就得到一个空模块。Buffer 在 Node.js 里是全局变量,所以用 ProvidePlugin 来提供它。
从 4.1.39 之后的版本起,钩子的第二个参数带有 rspack,也就是 Extension.js 用来编译的打包器。从它上面取插件类,你的项目就不需要自己安装 @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/config 中设置polyfill: true 会启用 webextension-polyfill,这是一个兼容层,让早于 148 的 Chromium 浏览器(带 devtools_page 时为早于 152)也能访问 browser.* API 命名空间。更新的版本原生提供 browser。它不会启用 Node 核心模块的 polyfill。
仅在某些库无法使用标准 Web API 时才使用 Node polyfill。
注意事项
- 不要假设扩展运行时可以访问文件系统;除非你有特定的、对浏览器安全的策略,否则把
fs保持为false。 - 在可能的情况下,优先用 Web Crypto(
crypto.subtle),而不是体积庞大的 Node crypto shim。 - Polyfill(Node API 的浏览器兼容替代品)会增大包体积,并可能影响扩展页面和 content script 的启动时间。
- 从 4.1.39 之后的版本起,
node:说明符读取的resolve.fallback键与它的裸名相同。在更早的版本里,它会让构建失败。

