1. 为什么现在还在聊 Webpack 4 到 5 的迁移前端构建工具这几年卷得厉害Vite、Rspack、Turbopack 轮番上阵新项目十有八九直接奔着 Vite 去了。但现实是大量存量项目还跑在 Webpack 4 上尤其是那些两三年前搭起来的中后台系统、组件库、多页应用。这些项目动辄几百个入口、上千个模块构建配置里塞满了各种 loader 和 plugin牵一发动全身不是说换就能换的。Webpack 5 正式版 2020 年 10 月就发了到现在已经迭代了好几年生态基本稳定。它带来的持久化缓存、模块联邦、更好的 Tree Shaking、Asset Modules 这些能力对存量项目来说收益是实打实的。我经手过好几个从 4 升到 5 的项目构建时间普遍能砍掉 30% 到 60%产物体积也有明显下降。但迁移过程绝对不是改个版本号就完事里面坑不少尤其是那些依赖老版本 loader 和 plugin 的项目稍不注意就是一连串报错。这篇内容适合两类人看一类是手上正好有 Webpack 4 项目要升级想找一份能直接照着做的操作手册另一类是想提前了解 Webpack 5 迁移会踩哪些坑做好心理准备。我会把整个迁移过程拆成几个阶段从依赖梳理、配置改造、loader 替换、plugin 升级到缓存策略和常见报错排查尽量把每一步的“为什么”和“怎么做”都讲清楚。文中涉及的具体项目信息我会做脱敏处理但操作步骤和参数都是真实可复现的。2. 迁移前的整体思路与依赖盘点2.1 先搞清楚你的项目到底依赖了什么很多人一上来就改 package.json 里的 webpack 版本然后 npm install接着就是满屏红字。这种做法不是不行但效率极低。我的习惯是先做一次完整的依赖盘点把项目里所有跟构建相关的东西列出来心里有个底。具体怎么做打开 package.json把所有 dependencies 和 devDependencies 里跟构建沾边的包都拎出来。重点关注这几类webpack 本体及其 CLIwebpack、webpack-cli、webpack-dev-serverloader 系列babel-loader、ts-loader、css-loader、style-loader、sass-loader、less-loader、file-loader、url-loader、raw-loader、eslint-loaderplugin 系列html-webpack-plugin、mini-css-extract-plugin、copy-webpack-plugin、clean-webpack-plugin、webpack-bundle-analyzer、terser-webpack-plugin、optimize-css-assets-webpack-plugin其他构建相关postcss-loader、autoprefixer、babel 相关 preset 和 plugin把这些包的当前版本号记下来然后去 npm 上查它们各自支持 Webpack 5 的最低版本。这一步很关键因为 Webpack 5 对 loader 和 plugin 的 API 做了一些调整老版本很可能直接报错。我一般会建一个表格来管理这些信息类似这样包名当前版本支持 Webpack 5 的最低版本是否需要替换webpack4.46.05.0.0是webpack-cli3.3.124.0.0是webpack-dev-server3.11.34.0.0是html-webpack-plugin3.2.05.0.0是babel-loader8.2.28.2.0否css-loader3.6.05.0.0是file-loader6.2.06.2.0建议替换为 asset modules这个表格不用做得多精致自己看得懂就行。它的作用是让你在后续升级时知道哪些包必须动哪些可以不动。2.2 迁移策略一步到位还是渐进式盘点完依赖之后接下来要决定迁移策略。我的经验是对于中小型项目入口少于 20 个构建配置在 300 行以内可以一步到位直接升到 Webpack 5遇到问题逐个解决。对于大型项目建议分两步走先把 Webpack 4 升到 4 的最新版本4.46.x确保所有 loader 和 plugin 也都是最新兼容版然后再整体切到 Webpack 5。为什么要先升到 4 的最新版因为 Webpack 4 后期版本已经对一些即将废弃的 API 做了警告提示先把这些警告处理掉迁移到 5 的时候会顺畅很多。这就像搬家之前先整理一遍东西该扔的扔该打包的打包搬起来才不费劲。还有一个策略上的选择要不要同时升级 Node.js 版本。Webpack 5 要求 Node.js 至少 10.13.0但实际用下来建议直接上 Node 14 或 16。Node 版本太低会限制一些新特性的使用而且很多新版本的 loader 和 plugin 也对 Node 版本有要求。我一般会在项目根目录加一个.nvmrc文件把 Node 版本固定下来避免团队里不同人用不同版本导致构建结果不一致。2.3 备份与回滚方案动手之前务必确保代码已经提交到版本控制并且打一个 tag。这不是废话我见过有人改了一半发现回不去只能硬着头皮往下走结果越改越乱。除了代码备份还要做一件事把当前的构建产物和构建时间记录下来。具体来说跑一次完整的生产构建记录下构建总耗时产物体积总体积和主要 chunk 的体积构建过程中是否有警告这些数据是迁移后的对比基准。没有基准你就没法判断迁移到底是优化了还是劣化了。我一般会用webpack-bundle-analyzer生成一份构建分析报告存成 HTML 文件迁移前后各跑一次对比着看。3. 核心配置改造与 loader 替换实操3.1 webpack.config.js 的结构性调整Webpack 5 的配置文件和 Webpack 4 相比整体结构变化不大但有几个地方必须改。首先是mode字段。Webpack 4 里如果不写mode会有警告但能跑。Webpack 5 里如果不写构建会直接报错。所以确保配置文件里明确写了mode: development或mode: production。其次是devtool的默认值变了。Webpack 4 的 development 模式下默认是evalWebpack 5 改成了eval-source-map。这个变化本身是好事source map 更准确了但如果你之前依赖eval的某些行为可能需要调整。再就是resolve配置里的fallback。Webpack 5 不再自动 polyfill Node.js 的核心模块比如path、fs、crypto如果你的代码里用到了这些模块需要在resolve.fallback里手动指定。比如module.exports { resolve: { fallback: { path: require.resolve(path-browserify), crypto: require.resolve(crypto-browserify), buffer: require.resolve(buffer/), }, }, };这个改动影响挺大的很多老项目里用了crypto-js或者直接引了 Node 的path模块升级后会报 Module not found: Error: Cant resolve path 之类的错误。解决办法就是装对应的 browserify 包然后在 fallback 里配好。还有一个容易忽略的点output.filename和output.chunkFilename里如果用了[hash]Webpack 5 里推荐改成[contenthash]。[hash]是基于整个构建的任何文件变了它都会变缓存利用率低。[contenthash]是基于文件内容的只有内容变了才变对持久化缓存更友好。3.2 那些必须替换的 loaderWebpack 5 最大的变化之一就是引入了 Asset Modules用来替代file-loader、url-loader和raw-loader。虽然这三个 loader 在 Webpack 5 里还能用但官方已经不再维护了建议尽早替换。替换方式很简单以图片为例原来是这样module: { rules: [ { test: /\.(png|jpg|gif)$/, use: [ { loader: url-loader, options: { limit: 8192, name: images/[name].[hash:8].[ext], }, }, ], }, ], }换成 Asset Modules 之后module: { rules: [ { test: /\.(png|jpg|gif)$/, type: asset, parser: { dataUrlCondition: { maxSize: 8192, }, }, generator: { filename: images/[name].[contenthash:8][ext], }, }, ], }这里type: asset会根据文件大小自动决定是内联成 base64 还是输出成文件maxSize就相当于原来url-loader的limit。generator.filename里的[ext]会自动带上点号所以不用写成.[ext]。对于字体文件一般不需要内联直接用type: asset/resource{ test: /\.(woff|woff2|eot|ttf|otf)$/, type: asset/resource, generator: { filename: fonts/[name].[contenthash:8][ext], }, }对于需要作为字符串引入的文件比如.txt或.md用type: asset/source相当于原来的raw-loader。css-loader和style-loader也需要升级。css-loader从 3.x 升到 5.x 或 6.xstyle-loader从 1.x 升到 2.x 或 3.x。升级后配置基本兼容但要注意css-loader的modules配置项有一些重命名比如localIdentName变成了localIdentName没变但context变成了localIdentContext。具体可以查官方 changelog。sass-loader和less-loader也要升到支持 Webpack 5 的版本。sass-loader建议 10.x 以上less-loader建议 8.x 以上。升级后如果用了additionalData之类的选项注意语法有没有变化。3.3 plugin 的升级与替换html-webpack-plugin从 3.x 升到 5.x 是必须的3.x 在 Webpack 5 下直接报错。升级后大部分配置兼容但chunksSortMode的默认值从auto变成了auto没变不过minify选项的行为有调整如果之前手动配了minify建议检查一下。mini-css-extract-plugin从 0.x 升到 1.x 或 2.x。升级后要注意filename和chunkFilename的写法推荐用[contenthash]。copy-webpack-plugin从 5.x 升到 9.x 或 10.x。这个插件升级跨度比较大配置变化也大。老版本里用from和to直接配新版本里推荐用patterns数组new CopyWebpackPlugin({ patterns: [ { from: public, to: public, globOptions: { ignore: [**/index.html], }, }, ], })clean-webpack-plugin在 Webpack 5 里可以直接用output.clean: true替代不需要额外装插件。这个改动挺香的少一个依赖。terser-webpack-plugin从 4.x 升到 5.x。Webpack 5 内置了 Terser 的压缩能力生产模式下默认就会压缩 JS所以如果你没有特殊的压缩配置可以直接删掉这个插件。如果需要自定义压缩选项再单独引入。optimize-css-assets-webpack-plugin建议替换成css-minimizer-webpack-plugin后者对 Webpack 5 支持更好配置也更清晰。3.4 持久化缓存配置Webpack 5 的持久化缓存是我最喜欢的功能之一。它能把构建结果缓存到文件系统下次构建时直接复用大幅提升构建速度。配置方式module.exports { cache: { type: filesystem, cacheDirectory: path.resolve(__dirname, .webpack_cache), buildDependencies: { config: [__filename], }, }, };buildDependencies里把配置文件本身加进去这样配置文件变了缓存会自动失效。cacheDirectory指定缓存存放位置建议加到.gitignore里。实测下来一个中型项目首次构建可能需要 60 秒二次构建能降到 10 秒以内。不过要注意持久化缓存对内存有一定要求如果项目特别大可能需要调整maxMemoryGenerations之类的参数。另外如果构建过程中出现了奇怪的缓存问题可以删掉缓存目录重新构建。4. 迁移后的验证与性能对比4.1 功能验证清单迁移完成后不能只看构建有没有报错还要验证功能是否正常。我一般会按这个清单过一遍开发环境下热更新是否正常修改代码后页面能否自动刷新生产构建产物能否正常运行所有页面和功能是否正常图片、字体、样式等静态资源是否正确加载代码分割是否生效懒加载的 chunk 能否按需加载source map 是否正常浏览器里能否定位到源码环境变量注入是否正确process.env相关代码是否按预期执行这个清单看起来简单但实际迁移中经常有项目在某个环节出问题。比如热更新失效可能是因为webpack-dev-server的配置没改对静态资源 404可能是 Asset Modules 的generator.filename配错了路径。4.2 构建性能对比功能验证通过后跑一次完整的生产构建和迁移前的数据做对比。我整理了一个对比表格模板指标Webpack 4Webpack 5变化首次构建耗时85s62s-27%二次构建耗时78s18s-77%产物体积JS2.4MB1.9MB-21%产物体积CSS320KB280KB-12%chunk 数量4238-4二次构建耗时的大幅下降主要归功于持久化缓存。产物体积的下降则来自更好的 Tree Shaking 和压缩优化。如果迁移后产物体积反而变大了可能是某些 loader 的配置没改对比如url-loader的limit没迁移到 Asset Modules 的maxSize导致小图片被输出成文件而不是内联。4.3 常见报错与排查思路迁移过程中遇到报错是常态我把几个高频问题整理成速查表报错信息可能原因解决办法Cant resolve pathNode 核心模块未 polyfill在 resolve.fallback 里配置对应包Module not found: Error: Cant resolve crypto同上装 crypto-browserify 并配置 fallbackTypeError: Cannot read property tap of undefinedplugin 版本不兼容升级 plugin 到支持 Webpack 5 的版本Error: NormalModuleFactory.beforeResolve is no longer supported使用了废弃的钩子改用新的钩子 APIChunk.entryModule is deprecated代码里用了废弃的 API替换为 Chunk.entryModule 的替代方案Cannot find module webpack-cli/bin/config-yargswebpack-cli 版本过低升级 webpack-cli 到 4.x 以上Error: Cannot find module webpack/lib/...直接引用了 webpack 内部模块改用公开 API 或升级相关依赖这些报错里最常见的是 Node 核心模块 polyfill 和 plugin 版本不兼容。前者通过resolve.fallback解决后者通过升级依赖解决。如果遇到不认识的报错先去报错涉及的包的 GitHub issues 里搜一下大概率有人已经踩过同样的坑。5. 实操心得与避坑经验5.1 关于 loader 的兼容性有一个坑我踩过两次babel-loader的版本。babel-loader8.x 是支持 Webpack 5 的但如果你用的是 7.x升级 Webpack 后可能会报错。解决办法就是升到 8.x。但升到 8.x 之后要注意babel-loader的cacheDirectory选项默认值变了如果之前依赖默认行为可能需要显式配置。还有eslint-loader这个包已经废弃了官方推荐用eslint-webpack-plugin替代。如果你项目里还在用eslint-loader迁移时顺手换掉不然 Webpack 5 下会报一堆警告。thread-loader也要注意如果之前用它来做多线程构建升级后要确认版本兼容。thread-loader3.x 支持 Webpack 5但配置方式和 2.x 略有不同主要是workers参数的默认值变了。5.2 关于持久化缓存的坑持久化缓存虽然香但有几个坑要注意。第一缓存目录不要放在项目源码目录里不然会被copy-webpack-plugin之类的插件复制到产物里。我一般放在项目根目录的.webpack_cache或者node_modules/.cache/webpack。第二如果项目里用了DefinePlugin注入环境变量缓存可能会导致环境变量更新后不生效。解决办法是在cache.buildDependencies里把环境变量文件也加进去或者干脆在切换环境时手动清缓存。第三CI 环境下持久化缓存可能不太适用因为每次构建都是全新的容器。这种情况下可以关掉持久化缓存或者把缓存目录挂载到持久化存储上。我一般会在 CI 配置里加一个环境变量来判断CI 环境下用内存缓存本地开发用文件系统缓存。5.3 关于产物体积的优化迁移到 Webpack 5 之后Tree Shaking 的效果会更好但前提是你的代码是 ESM 格式的。如果项目里混用了 CommonJS 和 ESMTree Shaking 效果会打折扣。建议检查一下package.json里的sideEffects字段把没有副作用的模块标记出来帮助 Webpack 更好地做 Tree Shaking。另外Webpack 5 的splitChunks默认配置也变了chunks的默认值从async变成了async没变但minSize的默认值从 30000 变成了 20000。这个变化会导致更多的小 chunk 被拆分出来如果觉得 chunk 太碎可以手动调大minSize。还有一个细节Webpack 5 的optimization.moduleIds和optimization.chunkIds默认值变成了deterministic这对长期缓存更友好。但如果你的项目依赖了 chunk id 的稳定性可能需要检查一下有没有影响。5.4 关于开发体验的改善Webpack 5 的webpack-dev-server升级到 4.x 之后配置方式有一些变化。比如contentBase改成了staticpublicPath改成了devMiddleware.publicPath。这些改动如果不注意开发服务器可能起不来。还有一个很实用的改进Webpack 5 支持experiments.topLevelAwait可以在顶层使用await。如果你的项目里有异步初始化逻辑这个特性挺方便的。不过要注意开启这个特性后产物的兼容性会受影响需要确认目标浏览器是否支持。webpack-dev-server4.x 还支持hot: only模式意思是热更新失败时不回退到刷新页面。这个模式在调试复杂状态时很有用避免页面刷新导致状态丢失。6. 迁移后的持续维护建议迁移完成不是终点后续的维护同样重要。我一般会做这几件事。第一把 Webpack 相关的依赖版本固定下来用package-lock.json或yarn.lock锁死。构建工具的版本波动很容易导致构建结果不一致锁定版本能避免很多莫名其妙的问题。第二定期检查 Webpack 的更新日志关注安全补丁和性能改进。Webpack 5 的 minor 版本更新一般比较平滑但 major 版本更新比如 5 到 6可能会有破坏性变更需要提前评估。第三把构建配置里的废弃警告处理掉。Webpack 5 在构建时会输出一些废弃 API 的警告这些警告不要忽略因为下一个大版本可能就直接移除了。我一般会在 CI 里加一个检查如果构建输出里有废弃警告就让构建失败强制处理。第四考虑逐步引入模块联邦。Webpack 5 的模块联邦是个很强大的功能适合微前端场景。如果项目有多个独立部署的子应用可以评估一下是否用模块联邦来共享依赖和组件。不过模块联邦的接入成本不低建议在迁移稳定后再考虑。第五关注构建产物的分析报告。我一般会定期跑webpack-bundle-analyzer看看有没有异常的体积增长。有时候某个依赖升级了体积突然变大不分析根本发现不了。最后分享一个小技巧如果迁移过程中遇到某个 loader 或 plugin 实在找不到支持 Webpack 5 的版本可以考虑用resolve.alias把它指向一个兼容层或者干脆用 Webpack 5 的原生能力替代。比如file-loader和url-loader就可以完全用 Asset Modules 替代不需要等 loader 作者更新。这种“绕过”的思路在迁移中很实用能帮你快速推进不被个别依赖卡住。