从 Webpack 4 升级到 5 时，我通常会先按照构建日志中出现的错误提示逐条处理，而不是一次性修改所有配置。因为升级失败时最常见的现象是构建直接报错或输出异常，这时优先解决报错项，再检查功能是否符合预期。下面是我在实际升级中保留的四个关键配置调整点，每个都附带适用场景、操作动作、验证方式和风险边界。

先确认构建日志中是否有“Module parse failed”

在Webpack 5中，模块类型系统进行了重构，原有的module.rules中type: 'javascript/auto'需要显式指定。如果项目中使用了自定义加载器或非标准模块语法，升级后可能出现解析错误。检查方法是在构建日志中查找'Module parse failed'错误，这类问题通常需要将rule的type改为'javascript/auto'或'javascript/esm'。风险边界在于过度使用'auto'可能影响tree-shaking效果，建议仅对特定文件类型启用。例如，如果某个配置文件使用了非标准的 AMD 模式，可以这样修改：

module: {
  rules: [
    {
      test: /\.config\.js$/,
      type: 'javascript/auto'
    }
  ]
}

修改后重新构建，观察是否还有相同错误。如果依然报错，则需要检查 loader 链中是否有不兼容的插件，此时可以临时启用 javascript/auto 确认问题范围，再逐步定位。

检查持久化缓存是否真的生效

Webpack 5默认启用了持久化缓存，但需要显式配置cache.type为'filesystem'才能生效。如果从4升级，旧版本可能未设置该选项，导致构建速度未提升。操作动作是在webpack.config.js中添加cache: { type: 'filesystem' }，并确保cache.cacheDirectory路径可写。常见坑是缓存文件可能占用磁盘空间，可通过cache.maxAge或手动清理来管理。检查构建日志中是否有'Persistent caching'字样确认启用。我通常会在首次升级后观察第二次构建的时间，如果发现明显缩短，说明缓存已生效。另外，如果项目使用 CI 环境，需要确保缓存目录在每次构建间可持久化，否则每次都是冷启动。

使用内置 clean 替代 CleanWebpackPlugin

Webpack 5内置了output.clean选项，可替代clean-webpack-plugin。升级后建议移除旧插件并启用内置功能，配置方式为output: { clean: true }。检查方法：构建后观察输出目录是否被清空。常见坑是clean选项默认在每次构建前清空整个输出目录，若想保留某些文件，需使用output.clean的{ keep: /文件名/ }模式。注意旧插件的配置项可能不兼容，需逐个核对。例如，如果之前使用了 clean-webpack-plugin 的 cleanOnceBeforeBuildPatterns，需要将其转换为 output.clean 的 keep 正则。我通常在注释掉旧插件后，先启用 clean: true，观察输出目录是否被完全清空，再根据需要添加 keep 规则。

处理 Node.js 核心模块 polyfill 冲突

Webpack 5 移除了自动 polyfill Node.js 核心模块，因此 require('crypto') 等调用会报错。判断条件是构建时出现 Module not found: Can't resolve 'crypto' 类错误。操作建议是安装对应 polyfill（如 crypto-browserify）并在 webpack 配置中通过 resolve.fallback 添加别名，例如 resolve: { fallback: { crypto: require.resolve('crypto-browserify') } }。风险边界在于过度引入 polyfill 会导致包体积膨胀，建议只针对实际使用的模块进行配置。如果项目依赖的第三方库中使用了多个 Node 模块，可以先用 webpack-ignore 或其他工具扫描依赖树，再决定是否添加 polyfill。修改完成后，构建日志中的对应 Module not found 错误应消失。如果某些模块在浏览器环境中根本不需要，可以考虑用 resolve.fallback: { crypto: false } 直接关闭，以减小包体积。

验证 Loader 默认导出变化

Webpack 5 要求 Loader 函数返回 JavaScript 代码时必须使用默认导出，且不再支持同步模式返回空值。如果自定义 loader 未遵循此规范，升级后构建会失败。判断条件：loader 执行后出现 Loader has been refactored to use the new API 警告。操作动作：将 loader 改写为导出函数，并使用 this.callback(null, result) 替代直接 return。风险边界在于部分旧 loader 兼容性差，可能需要寻找替代方案。例如，旧写法：

module.exports = function(source) {
  return source.replace(/foo/g, 'bar');
}

新写法：

module.exports = function(source) {
  this.callback(null, source.replace(/foo/g, 'bar'));
}

或使用 exports.default 导出。修改后，构建应不再报该警告。如果使用了第三方 loader 且无法修改，可以查看其更新版本或寻找社区替代。

关于 Module Federation 的额外提醒

如果项目使用了 Module Federation，升级到 Webpack 5 后需将插件从 @module-federation 替换为内置的 ModuleFederationPlugin。具体操作：移除原有依赖，在 webpack 配置中引入 const { ModuleFederationPlugin } = require('webpack').container，然后重新配置 exposes 和 remotes。常见坑：共享库版本冲突会导致运行时错误，需检查 shared 配置中的 singleton 和 requiredVersion 字段。检查构建产物中是否生成 remoteEntry.js 文件。这一步相对独立，通常在其他配置调整稳定后再处理。

升级完成后，建议先用 --mode production 构建一次，对比 output 目录结构和文件内容是否与旧版本一致。如果发现某些模块未正常加载，可以通过对比 webpack-analyzer 生成的依赖图排查。回滚时只需恢复旧的 webpack.config.js 和依赖版本即可。