从 Webpack 迁移到 Rspack 的完整指南与踩坑记录

团队维护了三年的 Webpack 项目，模块数超过 3000，冷构建需要 8 分钟，热更新 3~5 秒，开发体验已经严重拖累效率。本文记录我们迁移到 Rspack 的完整过程与踩坑。

迁移策略：渐进而非推倒重来

我们定下三条原则：

1. 双轨并行：新老构建同时产出，用产物对比脚本校验一致性；
2. 小步提交：每次只切换一个 loader，可独立回滚；
3. 灰度验证：先在内部环境跑一周，再上生产。

步骤一：安装与基础配置

Rspack 对 webpack.config.js 的兼容度很高，第一步往往是直接改命令行入口。

pnpm add -D @rspack/core @rspack/cli
# 把 build 脚本换成 rspack
rspack build --config rspack.config.js

大部分配置可以直接复制，仅需把少数 Webpack 专属字段替换为等价配置。

步骤二：逐个迁移 loader

我们遇到的几个真实问题：

• babel-loader：直接换成内置的 swc-loader 或 Rspack 内置转译，速度再上一个台阶；
• css-loader / style-loader：Rspack 内置了等价实现，删掉插件依赖即可；
• 自定义 loader：兼容层桥接后行为基本一致，但若 loader 读取了 Webpack 内部对象，则需要改写。

步骤三：校验产物一致性

这是最容易忽略却最关键的一步。我们写了一个脚本，对两套产物做对比：

• 资源清单（chunk 名称、数量）是否一致；
• 关键 chunk 的哈希与体积偏差是否在阈值内；
• 冒烟测试覆盖核心页面，确认运行时行为无回归。

最终收益

迁移完成后，冷构建从 8 分钟降到 55 秒，热更新从 3 秒降到 300 毫秒。更重要的是，团队不再因为「等构建」而频繁切换注意力。

结语

Rspack 对存量 Webpack 项目是最低风险的加速方案。但迁移的价值不在于工具本身，而在于过程中建立起来的产物一致性校验能力——这份资产会长期保护你的每一次升级。