升级 Webpack 5 并不只是把版本号一改那么简单，很多默认行为和内部机制发生了变化，如果沿用 Webpack 4 的旧配置直接启动，大概率会碰到一堆陌生的报错。先做一次依赖和 Node 版本检查，能省下不少排查时间。Webpack 5 要求 Node.js 10.13.0 及以上版本，但实际建议使用 Node 14 或更高的 LTS 版本，因为部分依赖包已经放弃对旧版 Node 的支持。检查命令可以使用 node -v，如果版本过低，先升级 Node 环境再进行后续操作。
除了 Node 版本，还需要同步升级与 Webpack 配合的工具链。webpack-cli 建议升级到 4.x 或更高的兼容版本，webpack-dev-server 如果仍然使用 3.x，需要升级到 4.x 才能与 Webpack 5 正常工作。使用 html-webpack-plugin、copy-webpack-plugin 等常用插件时，也要检查它们的 peerDependencies，旧版本可能只支持 Webpack 4。可以在项目根目录执行 npm outdated 查看可升级的包，然后一次性安装兼容版本。
升级前必须处理的依赖与版本检查
动手改配置之前，先完整记录当前的依赖版本和构建脚本，这样回退时不会手忙脚乱。Webpack 5 不再支持一些已经废弃的 API，例如 webpack.optimize.CommonsChunkPlugin 在 Webpack 4 中就已经被标记为弃用，但很多旧项目仍然在用。升级到 5 后会直接报错，需要改用 optimization.splitChunks。
执行 npm install --save-dev webpack@5 webpack-cli@4 后再运行一次构建，观察控制台输出的弃用警告。Webpack 5 会列出当前配置中已经失效的选项，这些警告就是迁移清单的关键来源。不要忽略任何一个 deprecation warning，因为它们往往对应着后续运行时错误。
如果项目中使用了 webpack-merge，也需要确认版本是否支持 Webpack 5 的配置结构。建议将 webpack-merge 升级到 5.x，旧版本在处理某些嵌套配置时可能产生结构差异。
配置文件中那些让人困惑的破坏性变更
Webpack 5 对 resolve 和 output 的部分默认值做了调整。一个典型的坑是 resolve.alias 不再接受数组形式，必须写成对象。比如以前可以写 alias: { 'old-lib': './src/new-lib' }，但数组写法 alias: [ { name: 'old-lib', alias: './src/new-lib' } ] 已经无效。升级时如果直接复制旧配置，会在解析模块时得到模糊的错误信息。
另一个高频问题是 output.publicPath 的默认行为变化。Webpack 4 中如果未指定，会基于 output.path 自动推断；而 Webpack 5 会自动推断为相对路径，在某些单页应用中会导致资源加载路径错误。建议升级后显式设置 output.publicPath: '/' 或项目实际路径，避免出现 404。
下面是一段典型的 Webpack 4 迁移到 Webpack 5 的配置对比，特别关注 resolve.fallback 的写法：
// Webpack 4 旧配置（省略无关部分）
module.exports = {
resolve: {
alias: {
'old-utils': './src/utils',
},
},
node: {
fs: 'empty',
net: 'empty',
},
};
// Webpack 5 新配置
module.exports = {
resolve: {
alias: {
'old-utils': './src/utils',
},
fallback: {
fs: false,
net: false,
crypto: require.resolve('crypto-browserify'),
},
},
};
注意 node 配置项在 Webpack 5 中已经被彻底移除，不能再通过 node.fs = 'empty' 这类方式处理 Node 核心模块。所有类似需求都要迁移到 resolve.fallback。
如何处理被移除的 Node.js 核心模块 polyfill
Webpack 5 最影响存量项目的一个变化是：不再自动为浏览器环境注入 Node.js 核心模块的 polyfill。如果你的代码或第三方依赖里出现了 require('buffer')、require('crypto')、require('stream') 等调用，升级后会直接抛出 Module not found: Can't resolve 'buffer' 一类的错误。这是因为 Webpack 4 会静默帮你打上 polyfill，而 Webpack 5 把这个决定权交还给了开发者。
要解决这个问题，通常需要安装对应的浏览器实现包，例如 buffer、crypto-browserify、stream-browserify，然后在 resolve.fallback 中显式配置。如果某些模块在你的应用里根本用不到，直接设置为 false 可以避免引入无用代码，减小产物体积。
下面是一个完整的处理示例：
const webpack = require('webpack');
module.exports = {
resolve: {
fallback: {
buffer: require.resolve('buffer/'),
crypto: require.resolve('crypto-browserify'),
stream: require.resolve('stream-browserify'),
util: require.resolve('util/'),
path: false,
fs: false,
},
},
plugins: [
new webpack.ProvidePlugin({
Buffer: ['buffer', 'Buffer'],
process: 'process/browser',
}),
],
};
这里用到 ProvidePlugin 是为了自动在模块中注入 Buffer 和 process 变量，因为很多依赖包虽然不再 require 这些核心模块，却仍然假设它们作为全局变量存在。如果构建后浏览器控制台报 process is not defined，通常就是缺少这个注入。
持久化缓存与构建性能提升配置
Webpack 5 自带持久化缓存能力，这是升级后立刻能感受到的性能红利。在 Webpack 4 中，二次构建需要依赖 cache-loader 或 hard-source-webpack-plugin 这类第三方方案，而且和压缩、热更新等环节的兼容性并不完美。Webpack 5 直接将缓存写入磁盘，通过 cache.type: 'filesystem' 开启后，首次构建时间和以前差不多，但后续构建速度会有数量级提升。
启用持久化缓存很简单，但要注意配置 buildDependencies，它告诉 Webpack 哪些配置文件的变化会导致缓存失效。如果不写这个字段，修改 webpack 配置后可能仍然使用旧缓存，导致构建结果和预期不一致。推荐把 webpack.config.js 以及所有被它 require 的本地文件都加入 buildDependencies。
module.exports = {
cache: {
type: 'filesystem',
buildDependencies: {
config: [__filename],
},
version: '1.0',
},
optimization: {
moduleIds: 'deterministic',
chunkIds: 'deterministic',
},
};
上面的 moduleIds 和 chunkIds 设置为 deterministic 也是 Webpack 5 对长期缓存的重要改进。Webpack 4 默认使用自增数字作为模块 ID，新增或删除模块时可能导致大量文件 hash 变化。改成确定性 ID 后，只有真正变化的模块会影响对应 chunk 的 hash，这对浏览器缓存命中率非常友好。
升级过程中如果遇到缓存导致的问题，可以先删除项目根目录下的 node_modules/.cache 目录，再重新构建。持久化缓存默认存放在这个位置，清理之后相当于从零开始构建，能快速排除缓存干扰。
升级后常见错误排查思路
迁移完成后，如果控制台出现 TypeError: Cannot read property 'tap' of undefined，基本可以确定是某个插件的版本与 Webpack 5 不兼容。解决办法是逐个检查插件，优先升级到官方标注支持 Webpack 5 的版本，实在找不到替代品再考虑更换方案。
另一个容易混淆的问题是 splitChunks 的默认行为变化。Webpack 5 对公共模块的拆分条件做了微调，某些在 Webpack 4 中被合并到 vendor 的模块，升级后可能被拆到更细的 chunk 中，导致加载顺序变化。如果出现 Cannot read property 'call' of undefined 这类运行时错误，优先检查是否缺少了 chunk 的预加载或依赖关系声明。
升级虽然会带来一些短暂的适配成本，但持久化缓存、更好的 tree shaking 和默认的确定性模块 ID，长期来看都能明显改善开发体验和线上缓存效率。对照上述几个关键点逐项排查，大部分项目都能在半天内完成迁移。