升级到 Webpack 5 之后，如果你在浏览器端项目中依赖了一些原本跑在 Node.js 环境里的库，就很可能在控制台看到类似 Uncaught ReferenceError: Buffer is not defined 或 process is not defined 的报错。这是因为 Webpack 5 彻底移除了过去自动为 Buffer、process、crypto 等 Node 核心模块注入浏览器 polyfill 的行为。在 Webpack 4 时代，这些 polyfill 会默默被打包进去，很多开发者甚至不知道它们的存在，升级后突然需要手动处理，难免会感到困惑。
这项变化源自 Webpack 团队对安全性和包体积的重新权衡。自动注入的 polyfill 往往体积庞大，且很多项目其实只用到其中一两个模块，全量注入造成了不必要的资源浪费。更关键的是，这些 polyfill 模拟的是 Node.js 环境，并非浏览器原生能力，可能引入潜在的安全风险或与浏览器 API 的冲突。因此，Webpack 5 选择把控制权交还给开发者：你需要明确告诉 Webpack，当遇到某个 Node 核心模块引用时，到底是用一个 polyfill 来替代，还是直接报错提示缺少模块。下面我们就从具体报错场景出发，一步步给出可落地的解决方案。
理解 Webpack 5 中 node 配置的变更
在 Webpack 4 及更早版本中，node 配置项用来控制是否对一系列 Node.js 全局变量和核心模块提供 polyfill。例如，设置 node.process = true 会让 Webpack 自动注入 process 的浏览器版本，设置 node.Buffer = true 则注入 buffer 模块的 polyfill。这些操作都是默认开启的，并且会跟随打包结果进入浏览器端产物。
Webpack 5 移除了整个 node 配置对象，并将相关行为改为 resolve.fallback 和 resolve.alias 的组合。在新的设计下，Webpack 不再主动提供一个“万能 polyfill 包”，而是要求开发者显式地为每个需要兼容的 Node 核心模块指定一个替代模块。如果你没有为某个模块（比如 path、os、crypto）配置 fallback，打包过程中该模块的引用就会保持不变，最终在浏览器中因找不到对应实现而抛出错误。
这种变化带来的直接影响是：如果你使用的第三方 npm 包内部引用了 Node 核心模块，比如某个工具库依赖 buffer 来处理二进制数据，或者依赖 stream 做管道操作，过去它们能“正常工作”只是因为 Webpack 帮你偷偷注入了 polyfill。现在这些引用会直接暴露出来，你必须根据实际情况决定是提供 browserify 版本的 polyfill，还是寻找替代实现，或者干脆通过 resolve.fallback 将该模块标记为 false（表示不需要任何实现，但可能导致运行时逻辑异常，需谨慎使用）。
手动配置 resolve.fallback 与安装对应 polyfill 包
最直接的解决方式是根据报错信息，逐个处理缺失的 Node 核心模块。Webpack 官方推荐使用 resolve.fallback 字段，将模块名映射到一个已有的 npm 包。常见需要处理的模块包括 buffer、stream、crypto、path、os、process 等。对应的 browserify 风格 polyfill 包通常命名规则为模块名前加 buffer/ 或者直接就是一个独立的 xxx-browserify 包。
以 buffer 模块为例，首先需要安装 polyfill：npm install buffer。然后在 webpack 配置文件的 resolve.fallback 中添加入口：
module.exports = {
resolve: {
fallback: {
"buffer": require.resolve("buffer/")
}
}
};
对于 process 全局变量，可以通过 ProvidePlugin 注入浏览器版本，也可以将其设为 false 来完全移除，前提是你的代码中不会真正用到它。更通用的做法是安装 process 包并配置：
const webpack = require('webpack');
module.exports = {
plugins: [
new webpack.ProvidePlugin({
process: 'process/browser',
}),
],
resolve: {
fallback: {
"process": require.resolve("process/browser")
}
}
};
类似地，crypto 模块通常替换为 crypto-browserify，stream 用 stream-browserify，path 用 path-browserify，os 用 os-browserify/browser 等。使用 require.resolve 可以确保使用当前项目中确切的包路径，避免模块解析歧义。
手动配置的好处是精确控制到底引入了哪些 polyfill，保持最终的包体积最小。同时，你也清楚每一项 polyfill 的作用和来源，方便后续维护。缺点则是当依赖的库引用了多个 Node 模块时，需要逐一排查和配置，比较繁琐。如果项目依赖复杂，可以借助下面介绍的自动化插件来批量处理。
使用 node-polyfill-webpack-plugin 一键式注入
对于不想逐个手动配置的场景，可以使用社区提供的 node-polyfill-webpack-plugin。这个插件模拟了 Webpack 4 时期的自动 polyfill 行为，一次性把所有常用的 Node 核心模块的浏览器版本注入到 Webpack 配置中。
安装插件：npm install node-polyfill-webpack-plugin --save-dev。然后将其添加到 Webpack 配置的 plugins 数组中：
const NodePolyfillPlugin = require("node-polyfill-webpack-plugin");
module.exports = {
plugins: [
new NodePolyfillPlugin()
]
};
这个插件内部已经预设了 buffer、crypto、stream、path、os、process、assert、util 等数十个模块的映射，并且会通过 ProvidePlugin 自动提供全局变量（如 process 和 Buffer）。你可以通过插件的 includeAliases 和 excludeAliases 选项来精细控制哪些模块需要注入，例如不想引入体积较大的 crypto-browserify 可以将其排除。
使用插件的优点是迁移成本极低，几乎不需要修改原有代码，就能让项目以一种接近 Webpack 4 的方式运行。但需要注意，这种方式会引入大量可能你其实并不需要的 polyfill，增加打包体积。如果你的应用对性能要求较高，或者最终只跑在较新的浏览器上，建议还是花些时间梳理依赖，采用手动配置的方式只引入必要的模块。它更适合作为一个快速恢复构建的临时方案，或用于内部工具、后台管理等对体积不敏感的场景。
用纯浏览器端实现替代 Node 核心模块
从长远来看，最干净的方案是让代码完全不依赖 Node 核心模块。如果你的代码或第三方库只是因为历史原因复用了 Node 的 Buffer 来处理二进制数据，完全可以用原生浏览器 API 替代。例如，使用 TextEncoder/TextDecoder 处理字符串与 Uint8Array 之间的转换，用 crypto.subtle 实现加解密，用 URL 和 URLSearchParams 代替 querystring 模块等。
对于自己编写的代码，可以直接切换到浏览器原生实现。例如原本依赖 Buffer.from() 的地方，可以改写为：
// 替代 Buffer.from('hello')
const encoder = new TextEncoder();
const uint8 = encoder.encode('hello');
二进制转换为字符串则可以使用 TextDecoder：
const decoder = new TextDecoder(); const str = decoder.decode(uint8);
如果依赖的第三方 npm 包大量使用了 Node 核心模块，且没有提供浏览器兼容版本，可以考虑寻找替代包。比如 crypto-js、js-sha3 等纯 JavaScript 实现的加密库，它们完全不依赖 Node 原生模块，可以在浏览器中直接使用。在项目选型时，留意包的 browser 字段或文档说明，优先选择对浏览器友好的库，可以从源头避免 Webpack 5 的 polyfill 烦恼。
还有一种折中策略是使用 Webpack 的 resolve.alias 将特定模块重定向到一个你自己编写的轻量 polyfill，只实现项目中用到的少数方法。这样既无需引入整个模块的完整模拟，又能精确满足需求。这种方式对包体积的控制最为精细，也最能体现 Webpack 5 给予开发者的灵活度。
Webpack 5node配置polyfill注入修改时间：2026-08-12 18:04:04