1. 升级 Webpack 4 到 Webpack 5#

Webpack 5 相比 Webpack 4 带来了诸多性能提升：

• 更好的持久化缓存：支持文件系统级别的缓存
• 更优的 Tree Shaking：减少打包体积
• 内置 Asset Modules：无需 file-loader 和 url-loader
• 改进的代码生成：更小的 bundle 体积

升级过程关键步骤：

1. 升级核心依赖：webpack 5.88+、webpack-cli 5.x、webpack-dev-server 4.x
2. 重构配置文件：拆分为 common/dev/prod 三个配置文件，职责分离
3. 适配 API 变化：devServer.contentBase → static、移除 cache 配置项
4. 升级相关插件：html-webpack-plugin 5.x、terser-webpack-plugin 5.x、fork-ts-checker 8.x
5. 测试验证：确保开发环境和生产构建正常

关键配置变化：

依赖版本升级#

1
{
2
  "webpack": "^5.88.0",
3
  "webpack-cli": "^5.1.4",
4
  "webpack-dev-server": "^4.15.1",
5
  "babel-loader": "^9.1.3",
6
  "css-loader": "^6.8.1",
7
  "style-loader": "^3.3.3",
8
  "mini-css-extract-plugin": "^2.7.6",
9
  "html-webpack-plugin": "^5.5.3",
10
  "fork-ts-checker-webpack-plugin": "^8.0.0",
11
  "terser-webpack-plugin": "^5.3.9",
12
  "@svgr/webpack": "^8.1.0"
13
}

配置文件重构#

在 script/ 目录下创建了三个配置文件：

• webpack.config.common.js：公共配置(entry、output、module rules、plugins)
• webpack.config.dev.js：开发环境配置(devServer、HMR)
• webpack.config.prod.js：生产环境配置(优化、压缩)

生产与开发打包的差异区分更精细：

这种差异化的配置策略带来的好处：

1. 开发阶段
   • 关闭压缩和最小化，加快构建速度
   • 生成源映射便于调试
   • 启用 HMR 实现秒级热更新
   • 文件名简洁，易于定位资源
2. 生产阶段
   • 启用全面的代码优化和压缩
   • 排除不必要的资源（如 moment locale）
   • 文件名含版本号，充分利用浏览器缓存
   • 不生成源映射，减小包体积
   • 严格的代码分割策略提升首屏加载性能

启用文件系统缓存#

1
cache: {
2
  type: 'filesystem',
3
  cacheDirectory: path.resolve(__dirname, '../.webpack_cache'),
4
  version: packageJson.version,
5
}

使用 Asset Modules 替代 url-loader#

1
{
2
  test: /\.(png|jpg|jpeg|gif|svg|woff|woff2|ttf|eot)$/,
3
  type: 'asset',
4
  parser: {
5
    dataUrlCondition: {
6
      maxSize: 10 * 1024,
7
    },
8
  },
9
}

优化代码分割策略#

1
splitChunks: {
2
  chunks: 'all',
3
  automaticNameDelimiter: '.',
4
  cacheGroups: {
5
    common_base: {
6
      test: /[\\/]node_modules[\\/](react|react-dom|mobx|mobx-react|axios|lodash|moment)[\\/]/,
7
      name: 'common-base',
8
      priority: 10,
9
    },
10
    common_chunk: {
11
      test: /[\\/]src[\\/]/,
12
      name: 'common-chunk',
13
      minChunks: 3,
14
      priority: 5,
15
    },
16
    vendors: {
17
      test: /[\\/]node_modules[\\/]/,
18
      name: 'vendors',
19
      priority: 3,
20
    },
21
  },
22
}

2. 精简项目依赖#

通过分析依赖关系，移除了项目中不必要的公共子库和公共包依赖：

• 移除了未使用的 @xxx-react-app/scripts
• 精简了部分业务组件库的引用
• 优化了按需加载的配置

这一步使模块数从 3975 个降低到 3503 个，减少了约 12%。

4. 优化 Loader 配置#

1
{
2
  test: /\.(js|jsx|ts|tsx)$/,
3
  // /@xxx-touch/, /@xxx-common/ 是通过link导入的依赖
4
  include: [PATH.appSrc, /@xxx-touch/, /@xxx-common/],
5
  use: [
6
    {
7
      loader: 'babel-loader',
8
      options: {
9
        cacheDirectory: true,
10
        cacheCompression: false,
11
        compact: !isEnvDevelopment,
12
      },
13
    },
14
  ],
15
}

关键优化点：

• 使用 include 精确限定处理范围
• 启用 cacheDirectory 利用缓存
• 关闭 cacheCompression 减少压缩开销

6. 热更新(HMR)优化#

优化前： 每次修改代码后，界面热更新时间需要等待 20 秒以上

优化后： 界面热更新小于 1 秒，接近秒更

原因分析：

1. Webpack 5 改进的 HMR 机制

   • Webpack 5 重写了 HMR 运行时，使用更高效的算法计算模块依赖关系
   • 改进的模块图(Module Graph)结构，减少了热更新时的模块遍历时间
   • 优化的 chunk 分割策略，减少了需要重新编译的模块数量

2. 文件系统缓存的作用

   1
   cache: {
   2
     type: 'filesystem',
   3
     cacheDirectory: path.resolve(__dirname, '../.webpack_cache'),
   4
   }
   

   • Webpack 5 的持久化缓存会缓存模块的编译结果
   • 热更新时只需重新编译修改的模块，未修改的模块直接从缓存读取
   • 大幅减少了重复编译的时间

3. 更精确的依赖追踪

   • Webpack 5 使用更精确的依赖追踪算法
   • 修改一个文件时，只会重新编译真正依赖它的模块
   • Webpack 4 可能会过度编译不相关的模块

4. 优化的 devServer 配置

   1
   devServer: {
   2
     compress: false,  // 开发环境关闭压缩，减少 CPU 开销
   3
     hot: true,        // 启用热模块替换
   4
   }
   

   • 关闭 compress 减少了每次热更新时的压缩开销
   • Webpack 5 的 webpack-dev-server 4.x 版本性能更优

5. 代码分割优化

   1
   optimization: {
   2
     runtimeChunk: 'single',
   3
     splitChunks: {
   4
       chunks: 'all',
   5
     },
   6
   }
   

   • 将 runtime 代码独立出来，减少主 bundle 的更新频率
   • 合理的 chunk 分割使得热更新影响范围更小

问题 1：为什么不用 swc-loader 替代 babel-loader？#

原因： 项目中使用了 MobX 4，而 swc-loader 对 MobX 4 的装饰器语法支持存在兼容性问题。

参考： https://github.com/swc-project/swc/issues/3389

解决方案： 继续使用 babel-loader，但通过以下方式优化：

• 启用 cacheDirectory 缓存编译结果
• 使用 include 精确限定处理范围
• 升级到 babel-loader 9.x 版本

问题 2：为什么没有使用 thread-loader？#

原因：

1. thread-loader 与项目中使用的 @unocss/webpack 插件存在冲突
2. 对于中小型项目，启动线程池的开销可能超过并行编译的收益

解决方案： 移除 thread-loader，通过 Webpack 5 的文件系统缓存和其他优化手段提升速度。

问题 3：CaseSensitivePathsPlugin 耗时较长(11.37s)#

分析： 这个插件用于检查路径大小写一致性，在大型项目中会遍历所有模块，导致耗时较长。

权衡： 虽然耗时较长，但这个插件对于跨平台开发很重要(避免 Mac/Linux 与 Windows 之间的路径问题)，因此保留。

后续优化方向： 可以考虑仅在 CI/CD 环境中启用，开发环境禁用。

优化成果#

通过本次优化，我们实现了：

✅ 构建时间从 42.55s 降低到 19.26s，提升 54.7%

✅ 模块数量减少 12%，打包体积更小

✅ 启用文件系统缓存，二次构建更快

✅ 配置结构更清晰，易于维护

✅ 为后续迁移到 React 18 和 MobX 6 奠定基础

技术要点回顾#

1. Webpack 5 升级要点
   • 依赖版本升级(webpack、loader、plugin)
   • 配置文件重构(common/dev/prod 分离)
   • 启用文件系统缓存
   • 使用 Asset Modules 替代 url-loader
2. 性能优化技巧
   • 精确使用 include/exclude 限定 loader 范围
   • 启用 babel-loader 缓存
   • 优化代码分割策略
3. 兼容性处理
   • MobX 4 装饰器语法兼容（保留 babel-loader）

后续优化方向#

1. 继续减少模块数量：进一步分析依赖关系，按需加载更多模块
2. CaseSensitivePathsPlugin 优化：仅在 CI/CD 环境启用
3. 考虑升级到 MobX 6：解决装饰器兼容性问题后，可以尝试 swc-loader
4. 启用 Module Federation：实现微前端架构，进一步提升构建效率
5. 增量编译：利用 Webpack 5 的增量编译能力，进一步提升二次构建速度

经验总结#

1. 性能优化要先测量再优化：使用 speed-measure-webpack-plugin 定位瓶颈
2. 新版本不一定都要用新特性：根据项目实际情况选择(如 thread-loader)
3. 兼容性比性能更重要：确保项目稳定运行是第一优先级
4. 配置清晰比配置复杂更好：分离 dev/prod 配置，便于维护

相关资源：

• Webpack 5 官方迁移指南
• Webpack 构建速度优化实践
• 项目 Webpack 5 迁移文档