企业官网建设流程全解析

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 本体及其 CLI：webpack、webpack-cli、webpack-dev-server
• loader 系列：babel-loader、ts-loader、css-loader、style-loader、sass-loader、less-loader、file-loader、url-loader、raw-loader、eslint-loader
• plugin 系列：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 做了一些调整，老版本很可能直接报错。

我一般会建一个表格来管理这些信息，类似这样：

这个表格不用做得多精致，自己看得懂就行。它的作用是让你在后续升级时知道哪些包必须动，哪些可以不动。

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 模式下默认是eval，Webpack 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: Can't resolve 'path'" 之类的错误。解决办法就是装对应的 browserify 包，然后在 fallback 里配好。

还有一个容易忽略的点：output.filename和output.chunkFilename里如果用了[hash]，Webpack 5 里推荐改成[contenthash]。[hash]是基于整个构建的，任何文件变了它都会变，缓存利用率低。[contenthash]是基于文件内容的，只有内容变了才变，对持久化缓存更友好。

3.2 那些必须替换的 loader

Webpack 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.x，style-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 构建性能对比

功能验证通过后，跑一次完整的生产构建，和迁移前的数据做对比。我整理了一个对比表格模板：

二次构建耗时的大幅下降主要归功于持久化缓存。产物体积的下降则来自更好的 Tree Shaking 和压缩优化。如果迁移后产物体积反而变大了，可能是某些 loader 的配置没改对，比如url-loader的limit没迁移到 Asset Modules 的maxSize，导致小图片被输出成文件而不是内联。

4.3 常见报错与排查思路

迁移过程中遇到报错是常态，我把几个高频问题整理成速查表：

这些报错里，最常见的是 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 和 ESM，Tree 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改成了static，publicPath改成了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 作者更新。这种“绕过”的思路在迁移中很实用，能帮你快速推进，不被个别依赖卡住。