1. 为什么我要把老项目从 Webpack 4 拽到 Webpack 5手里有个跑了三年多的后台管理系统最早是 2019 年搭的Webpack 4.41 配 babel 7一直没动过。倒不是不想升是每次打开package.json看到那一长串 loader 和 plugin 的版本号就头疼。真正让我下决心动手的是去年冬天一次构建时间统计冷启动 47 秒热更新平均 3.2 秒改一行样式要等三秒才能看到效果这谁受得了。Webpack 5 带来的东西其实很实在持久化缓存、更好的 tree shaking、内置的 Asset Modules、不再需要url-loader和file-loader、Node.js polyfill 的自动处理策略调整。这些不是花架子持久化缓存能让二次构建直接砍掉一大半时间Asset Modules 能少装好几个依赖。但问题在于Webpack 4 到 5 不是那种改个版本号就能跑起来的升级中间有一堆 breaking changes尤其是 polyfill 那块坑最深。这篇东西适合谁看如果你手上有个 Webpack 4 的老项目想升到 5 但又怕踩坑或者你已经尝试升了但被一堆报错劝退那接下来的内容应该能帮你省不少时间。我不打算写成官方文档的翻译版而是按我实际迁移的顺序把每一步为什么这么做、遇到什么问题、怎么解决的都摊开讲。有些地方我走了弯路也会标出来让你绕过去。先说结论整个迁移我花了大概两个工作日其中一半时间耗在 polyfill 和第三方依赖的兼容性上。如果提前知道这些坑一天之内搞定是没问题的。2. 迁移前的准备工作与版本选型2.1 先摸清家底依赖清单和构建配置盘点动手之前别急着改package.json先把现有项目的构建链路完整过一遍。我当时的做法是打开webpack.config.js把所有 loader、plugin、resolve 配置、optimization 配置逐项列出来然后对照 Webpack 5 的变更清单标记哪些需要改。具体要盘点的东西包括所有loader及其版本特别是babel-loader、ts-loader、css-loader、style-loader、sass-loader、postcss-loader所有plugin重点看html-webpack-plugin、mini-css-extract-plugin、copy-webpack-plugin、clean-webpack-plugin、webpack-bundle-analyzerresolve.fallback和node配置项这两个在 Webpack 5 里行为变了有没有用到url-loader、file-loader、raw-loader这三个在 Webpack 5 里可以用 Asset Modules 替代devServer的配置Webpack 5 的 devServer 版本也升了大版本我当时的项目用了url-loader处理图片、file-loader处理字体、raw-loader处理 markdown 模板这三个在迁移后全部删掉了换成type: asset系列配置依赖少了三个配置反而更清晰。提示盘点的时候建议把package.json里所有devDependencies和dependencies都过一遍凡是跟构建相关的去 npm 上看一下最新版本是否支持 Webpack 5。有些包虽然能用但会打 warning看着烦。2.2 Node.js 版本和 Webpack 5 小版本怎么选Webpack 5 对 Node.js 版本有要求最低 10.13.0但实际用下来建议至少 14.x最好 16.x 以上。我一开始在 Node 12 上跑持久化缓存偶尔会出问题升到 16 之后就没再遇到。Webpack 5 的小版本选择上不建议一上来就追最新。我选的是 5.76.0原因是这个版本相对稳定社区里反馈的 bug 比较少而且webpack-dev-server4.13.x 跟它配合没问题。太新的版本有时候会引入一些实验性改动老项目升上去容易碰到意外。webpack-cli也要一起升Webpack 5 需要webpack-cli4.x 以上。我当时锁的是 4.10.0用下来没什么问题。版本组合我列个表方便你对照包名Webpack 4 时期版本迁移后版本说明webpack4.41.25.76.0核心必须升webpack-cli3.3.104.10.0命令行工具必须升webpack-dev-server3.9.04.13.1开发服务器大版本升级html-webpack-plugin3.2.05.5.0模板插件大版本升级mini-css-extract-plugin0.8.02.7.2样式提取大版本升级babel-loader8.0.69.1.2需要配合 babel 7.12这张表里的版本是我实际跑通的组合你可以直接抄但要注意你的项目里如果有其他插件依赖这些包的旧版本可能需要一起调整。2.3 分支策略和回滚方案迁移之前一定要开新分支别在主分支上直接改。我的做法是拉一个feature/webpack5-migration分支每完成一个阶段就 commit 一次这样万一某个改动导致构建彻底跑不起来可以快速回退到上一个可用状态。另外建议在迁移前把node_modules和 lock 文件都备份一份或者至少把package-lock.json提交到 git。因为升级过程中你会反复装依赖有时候版本冲突会把 lock 文件搞乱有个干净的备份能省很多事。回滚方案也简单如果迁移到一半发现某个核心依赖死活不兼容 Webpack 5那就先回退到 Webpack 4把不兼容的依赖单独处理等它更新了再继续。我当时的项目里有一个内部工具包用了老版本的loader-utils导致构建报错后来是临时用resolutions字段强制指定版本才解决的。3. 核心配置改造从 loader 到 Asset Modules3.1 资源处理方式的彻底改变Webpack 4 时代处理图片、字体、媒体文件标准做法是装url-loader和file-loader然后在 rules 里配test和use。Webpack 5 引入了 Asset Modules把这套东西内置了不需要额外装 loader。具体对应关系是这样的url-loader的limit选项对应type: asset加上parser.dataUrlCondition.maxSizefile-loader对应type: asset/resourceraw-loader对应type: asset/source我原来的配置是这样的// Webpack 4 的写法 { test: /\.(png|jpe?g|gif|svg)$/, use: [ { loader: url-loader, options: { limit: 8192, name: img/[name].[hash:8].[ext] } } ] }迁移后改成// Webpack 5 的写法 { test: /\.(png|jpe?g|gif|svg)$/, type: asset, parser: { dataUrlCondition: { maxSize: 8192 } }, generator: { filename: img/[name].[contenthash:8][ext] } }注意几个细节[hash]在 Webpack 5 里已经不推荐用了要换成[contenthash]因为[hash]是整个构建的哈希任何文件变了它都会变缓存效果差。[ext]现在自带点号不需要写成.[ext]写错了会变成两个点。字体文件的处理类似原来用file-loader的现在直接type: asset/resource然后配generator.filename就行。注意如果你项目里用了svg作为 React 组件通过svgr/webpack那svg的处理规则要单独拎出来不能跟图片混在一起。我当时的做法是把svg的 rule 放在图片 rule 之前并且用include限定只处理图标目录。3.2 CSS 提取和压缩的配置调整mini-css-extract-plugin从 0.x 升到 2.x 之后配置方式基本没变但有几个细节要注意。首先是filename和chunkFilename的写法[contenthash]替代了[hash]。其次是publicPath的处理Webpack 5 里如果用了output.publicPath为automini-css-extract-plugin需要显式指定publicPath否则 CSS 里的图片路径会出错。我当时的配置new MiniCssExtractPlugin({ filename: css/[name].[contenthash:8].css, chunkFilename: css/[name].[contenthash:8].chunk.css, ignoreOrder: true })ignoreOrder这个选项建议打开不然 CSS 模块顺序不一致的时候会报一堆 warning。虽然不影响功能但看着糟心。CSS 压缩方面Webpack 4 时代常用optimize-css-assets-webpack-plugin这个包在 Webpack 5 里已经废弃了要换成css-minimizer-webpack-plugin。配置方式差不多但它是放在optimization.minimizer里的const CssMinimizerPlugin require(css-minimizer-webpack-plugin); optimization: { minimizer: [ ..., new CssMinimizerPlugin() ] }注意那个...是必须的它表示保留 Webpack 5 默认的 JS 压缩器TerserPlugin不然你的 JS 就不会被压缩了。这个坑我当时踩过构建完发现 JS 体积没变排查了半天才发现是 minimizer 覆盖了默认配置。3.3 polyfill 策略的彻底重构这是整个迁移里最麻烦的部分没有之一。Webpack 4 会自动给 Node.js 核心模块注入 polyfill比如crypto、buffer、stream这些你在浏览器代码里require(crypto)也能跑。Webpack 5 把这个行为取消了默认不注入任何 polyfill理由是大部分项目其实用不到自动注入会让包体积无谓增大。但问题是很多老项目确实依赖了这个行为。我当时的项目里有个加密工具库用了crypto还有个地方用了buffer迁移后直接报Module not found: Error: Cant resolve crypto。解决方案有三种第一种是装node-polyfill-webpack-plugin它会自动帮你把常用的 Node 核心模块 polyfill 都注入进去。这个方案最省事但缺点是包体积会变大因为它把所有 polyfill 都打进去了。第二种是按需安装对应的 polyfill 包然后在resolve.fallback里指定。比如resolve: { fallback: { crypto: require.resolve(crypto-browserify), buffer: require.resolve(buffer/), stream: require.resolve(stream-browserify) } }这个方案更精细只 polyfill 你实际用到的模块包体积可控。缺点是你得一个个排查哪些模块需要 polyfill。第三种是如果那个依赖只在 Node 环境用浏览器环境不用那可以在resolve.fallback里把它设为false直接告诉 Webpack 不用管resolve: { fallback: { fs: false, path: false } }我最后用的是第二种加第三种混合的方案crypto和buffer用 polyfillfs和path设为false。这样包体积只增加了大概 30KB可以接受。提示排查哪些模块需要 polyfill 有个技巧先全部设为false然后构建看报错信息里缺哪个就补哪个。比一个个试快得多。4. 插件升级与开发体验优化4.1 常用插件的版本适配和配置变更html-webpack-plugin从 3.x 升到 5.x大部分配置兼容但有几个地方要注意。首先是chunksSortMode的默认值变了从auto变成了auto但排序逻辑有调整如果你依赖特定的 chunk 注入顺序需要显式指定。其次是minify选项5.x 里如果没装html-minifier-terser压缩功能不会生效需要单独装。我当时的配置new HtmlWebpackPlugin({ template: public/index.html, filename: index.html, inject: true, minify: { removeComments: true, collapseWhitespace: true, removeAttributeQuotes: true }, chunksSortMode: manual, chunks: [vendors, common, main] })copy-webpack-plugin从 5.x 升到 11.x配置变化比较大。原来的from/to写法还能用但推荐用patterns数组。另外ignore选项改成了globOptions.ignore写法变了new CopyWebpackPlugin({ patterns: [ { from: public, to: public, globOptions: { ignore: [**/index.html, **/.DS_Store] } } ] })clean-webpack-plugin在 Webpack 5 里可以直接用output.clean: true替代不需要额外装插件了。这个改动很舒服少一个依赖。webpack-bundle-analyzer升级到 4.x 后用法没变但建议只在需要的时候才启用不然每次构建都弹个窗口很烦。我的做法是加个环境变量控制const BundleAnalyzerPlugin require(webpack-bundle-analyzer).BundleAnalyzerPlugin; const plugins [ // ...其他插件 ]; if (process.env.ANALYZE) { plugins.push(new BundleAnalyzerPlugin()); }4.2 持久化缓存的实际效果和配置要点Webpack 5 的持久化缓存是我最期待的功能实际用下来确实香。配置很简单cache: { type: filesystem, cacheDirectory: path.resolve(__dirname, node_modules/.cache/webpack), buildDependencies: { config: [__filename] } }buildDependencies.config指向配置文件本身这样配置文件改了缓存会自动失效。cacheDirectory建议放在node_modules/.cache下面这样清理依赖的时候会一起清掉不会留垃圾。实测效果冷启动从 47 秒降到 42 秒左右因为要写缓存但二次启动直接降到 8 秒热更新从 3.2 秒降到 0.8 秒。这个提升非常明显尤其是热更新改样式几乎秒出。但持久化缓存也有坑。首先是缓存有时候会“假命中”就是明明代码改了但构建结果没变。这种情况一般是buildDependencies没配好或者某些 loader 的缓存策略有问题。解决办法是遇到诡异问题时先删掉缓存目录重新构建一次。其次是 CI 环境里缓存的处理。如果 CI 每次都是干净环境那持久化缓存反而会增加构建时间因为要写缓存但下次用不到。我的做法是在 CI 里通过环境变量关掉缓存cache: process.env.CI ? false : { type: filesystem, // ... }4.3 devServer 升级后的热更新和代理配置webpack-dev-server从 3.x 升到 4.x配置项有几个变化。hot和hotOnly合并成了hotcontentBase改成了staticpublicPath移到了devMiddleware下面。我原来的配置// Webpack 4 的 devServer devServer: { contentBase: path.join(__dirname, public), publicPath: /, hot: true, hotOnly: true, port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }迁移后// Webpack 5 的 devServer devServer: { static: { directory: path.join(__dirname, public) }, devMiddleware: { publicPath: / }, hot: true, port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }hotOnly去掉了因为hot: true已经包含了“热更新失败不刷新页面”的行为。代理配置基本没变但如果你用了pathRewrite写法还是一样的。还有一个变化是client配置4.x 里可以配overlay来控制报错是否在浏览器上覆盖显示client: { overlay: { errors: true, warnings: false } }这个建议打开errors关掉warnings不然 warning 多了满屏都是很影响调试。5. 踩坑实录与常见问题排查5.1 构建报错Module not found 的几种典型情况迁移过程中最常见的报错就是Module not found原因五花八门我整理了几种典型情况第一种是 Node 核心模块缺失前面 polyfill 那节已经讲了解决办法就是配resolve.fallback。第二种是文件扩展名解析问题。Webpack 5 对resolve.extensions的默认值有调整如果你的项目里用了.mjs或者.cjs文件需要显式加到extensions数组里resolve: { extensions: [.js, .jsx, .ts, .tsx, .json, .mjs, .cjs] }第三种是package.json里的exports字段。Webpack 5 开始支持这个字段但有些老包的exports配置不完整导致 Webpack 找不到入口文件。解决办法是在resolve.alias里直接指向具体文件或者用resolve.mainFields调整解析顺序。第四种是大小写敏感问题。Webpack 5 在 Linux 环境下对文件路径大小写更严格import ./Component和import ./component会被当成两个不同的文件。这个在 Mac 上开发没问题一到 CI 就报错。解决办法是统一用编辑器插件检查路径大小写或者用case-sensitive-paths-webpack-plugin。5.2 样式丢失和 CSS 顺序错乱的处理迁移后如果发现样式没生效先检查mini-css-extract-plugin的publicPath配置。Webpack 5 的output.publicPath默认是automini-css-extract-plugin在 2.x 里需要显式指定publicPath否则 CSS 里引用的图片路径会变成相对路径导致 404。配置方式new MiniCssExtractPlugin({ filename: css/[name].[contenthash:8].css, chunkFilename: css/[name].[contenthash:8].chunk.css, ignoreOrder: true })如果样式顺序错乱比如 A 组件的样式覆盖了 B 组件的样式但预期是反过来那大概率是 CSS 模块顺序问题。ignoreOrder: true可以消除 warning但不会解决顺序问题。真正的解决办法是调整optimization.splitChunks的配置把 CSS 提取到单独的 chunk 里或者用style-loader在开发环境替代mini-css-extract-plugin。我当时的做法是开发环境用style-loader生产环境用mini-css-extract-plugin这样开发时样式顺序按引入顺序来不会有意外覆盖。5.3 第三方依赖不兼容的应急方案有些第三方包可能还没适配 Webpack 5构建时报错。我遇到过一个内部工具包用了老版本的loader-utils导致this.getOptions is not a function报错。应急方案有几种第一种是用resolutions字段强制指定版本npm 用overrides{ resolutions: { loader-utils: ^2.0.0 } }第二种是用alias把有问题的包指向一个兼容版本resolve: { alias: { problematic-package: path.resolve(__dirname, node_modules/problematic-package/dist/compatible.js) } }第三种是如果那个包只在构建时用不影响运行时可以暂时用IgnorePlugin忽略掉new webpack.IgnorePlugin({ resourceRegExp: /^problematic-package$/ })但这种方法要谨慎忽略之后如果代码里真的用到了这个包运行时会报错。5.4 常见问题速查表报错信息可能原因解决办法Module not found: Cant resolve cryptoNode 核心模块未 polyfill配 resolve.fallback 或装 node-polyfill-webpack-pluginthis.getOptions is not a functionloader 版本不兼容升级 loader 或用 resolutions 强制指定版本Conflict: Multiple chunks emit assets to the same filename输出文件名冲突检查 output.filename 和 chunkFilename 是否重复Chunk.entrypoints: Use Chunks.groupsIterable插件版本过旧升级插件到支持 Webpack 5 的版本Cannot read property tap of undefined插件钩子 API 变更升级插件或找替代方案CSS 中图片 404publicPath 配置问题显式指定 mini-css-extract-plugin 的 publicPath热更新不生效devServer 配置变更检查 hot 和 client 配置提示遇到报错先看报错信息里的包名和版本号去 npm 上查这个包的最新版本是否支持 Webpack 5。大部分问题都是版本不匹配导致的升级就能解决。6. 迁移后的效果验证与性能对比6.1 构建时间和包体积的实际数据迁移完成后我做了几组对比测试数据如下指标Webpack 4Webpack 5变化冷启动构建47s42s-10.6%二次构建有缓存47s8s-83%热更新响应3.2s0.8s-75%生产包体积gzip 后1.82MB1.64MB-9.9%首屏 JS 体积gzip 后486KB412KB-15.2%包体积的减少主要来自 tree shaking 的改进和 polyfill 的按需引入。Webpack 5 的 tree shaking 对 ESM 模块的静态分析更准确一些没用到的导出能被正确剔除。另外sideEffects: false的标记在 Webpack 5 里效果更好如果你们的包有正确标记收益会更明显。6.2 运行时性能和开发体验的变化运行时性能方面首屏加载时间从 2.1 秒降到 1.8 秒本地测试Fast 3G 模拟主要贡献是包体积减小和代码分割更合理。Webpack 5 的splitChunks默认策略有调整对公共依赖的提取更智能重复代码更少。开发体验的提升更直观。热更新从 3 秒降到 1 秒以内改样式几乎无感。持久化缓存让重启项目的成本大幅降低以前改完配置重启要等将近一分钟现在十秒内就能继续干活。还有一个隐性收益是构建日志更清晰了。Webpack 5 的 warning 和 error 分类更明确哪些是真正的错误、哪些只是提示一眼就能分清。Webpack 4 时代那种满屏黄字的情况好了很多。6.3 后续优化方向迁移完成后还有几个可以继续优化的点。一是splitChunks的精细化配置可以根据实际业务调整cacheGroups把 React、Vue 这类框架单独打包利用浏览器缓存。二是moduleIds和chunkIds设为deterministic让长期缓存更稳定。三是如果项目里有大量图片可以考虑用image-minimizer-webpack-plugin做压缩。另外 Webpack 5 的experiments里有一些实验性功能比如topLevelAwait、outputModule等如果项目用得到可以开启但生产环境建议谨慎等稳定了再说。我个人在实际操作中的体会是Webpack 4 到 5 的迁移难点不在配置本身而在依赖生态的适配。核心配置改起来其实很快真正耗时间的是排查那些不兼容的第三方包。所以如果你准备迁移建议先把依赖清单过一遍把明显不兼容的包提前升级或找替代方案这样正式迁移的时候会顺畅很多。另外持久化缓存一定要开这是 Webpack 5 最实用的功能没有之一。