我们组一个 React 中后台项目。跑了三年多，累计 452 个模块。Webpack 5 打包一次生产环境接近两分钟。CI 排队时看着进度条，总觉得在浪费生命。上周刷 GitHub 看到 Rspack 已经 2.x 了release note 里写了不少性能调整，我决定趁这周需求间隙试试迁移。说起来，官方文档看起来挺清爽：改个配置文件名。换几个 loader，完事。半天就够了吧，结果折腾了两天——文档写得很清楚，但坑都在文档没写的地方。

SWC 替换 Babel，上来就给我一棒子

痛点：从 Babel 切到 SWC 时语法特性不兼容导致编译报错。

配置文件改名那步确实没啥好说的。webpack.config.js 改成 rspack.config.jswebpack 换成 @rspack/core内置插件名字换一换，五分钟搞定。跑 npx rspack build直接就开始编译了没报错。

接下来把 babel-loader 换成 builtin:swc-loader按照文档示例改配置：

// 改之前
{
至于test，/.sx?$/,loader: 'babel-loader',options: {
presets:。plugins:
}
}
// 改之后
{
从test来看，/.sx?$/,loader: 'builtin:swc-loader',options: {
再看jsc，{
从parser来看，{
至于syntax，'typescript',tsx: true,decorators: true
}。transform: {
至于react，{ runtime: 'automatic' },legacyDecorator: true
}
}
}
}

编译炸了。报错大概长这样：

Error: Expected ';','}' or 
- src/utils/legacy-parser.ts::
| |
const result = arr?.filter
^

痛点：可选链 ?. 报语法错误，我以为是项目里有什么奇怪语法，却不是。

可选链、空值合并等，而 SWC 必须在 jsc.target 中显式指定支持的 ECMAScript 版本。

// 最终能用的版本
{
说到test，/.sx?$/,loader: 'builtin:swc-loader',options: {
jsc这方面，{
再看parser，{
syntax这方面，'typescript',tsx: true,decorators: true
},transform: {
再看react，{ runtime: 'automatic' },legacyDecorator: true
},target: 'es2020' // 加上这行就好了
}
}
}

痛点：.js 文件里也用了 decorators。TS parser 不认 JS 文件里的装饰器，需要单独写规则：

{
说到test，/.js$/,loader: 'builtin:swc-loader',options: {
说到jsc，{
parser : { syntax : 'ecmascript',decorators : true },transform : { legacyDecorator : true }
}
}
}

Babel 那“一把梭” 的日子一去不复返了；SWC 配置粒度更细，但必须真正了解自己在配什么。

*附注*: 项目里用了 babel-plugin-styled-components而 SWC 没有对应插件。我们趁机把 styled‑components 换成 CSS Modules。如果你的项目 heavily 使用 styled‑components，这块迁移成本需要额外评估。

痛点：Cascading StyleSheets 在迁移后全部失效，导致页面样式乱套。

Babel 替换完后编译通过我以为最难的已经搞定，于是跑起来看看效果——页面出来了却发现所有样式都乱了。我们在 Webpack 中使用的 CSS Modules 命名方式是：

// Webpack 的配置
{
loader : 'css-loader',options : {
modules : { localIdentName : '_' }
}
}

I initially wrote following in Rspack:

// 有问题的版本
{
test : /.module.css$/,use :,type : 'css/module'
}

The problem is that setting type:'css/module'` triggers Rspack’s built‑in CSS Modules handling。 which ignores #localIdentName#` option of external css‑loader. The two mechanisms cannot be mixed.

The fix is to move naming configuration into Rspack’s module parser:

// 最终正确的版本
module : {
parser : {
'css/module' : {
exports : 'local',localIdentName : '_'
}
},rules :
}
]
}

Cascade style恢复后还要注意一点：如果你的项目不是用 “`.module.css`” 后缀区分，而是在 Webpack 中。说起来，

• `copy-webpack-plugin` → `rspack.CopyRspackPlugin`： 配置格式基本一样。这块倒是丝滑，
• `fork-ts-checker-webpack-plugin` → `ts-checker-rspack-plugin`： 注意 Rspack 推荐搭配 TypeScript .x 使用；我们仍在 TS .x，暂时兼容但最好计划升级。
• `thread-loader` 与 `cache-loader`： 直接删掉即可——Rspack 本身基于 Rust 多线程编译。并内置持久化缓存，这两个 loader 在 Webpack 时代用来加速，现在反而拖后腿。
• `webpack-dev-server` → `rspack serve`： 代理配置大部分兼容。但 `historyApiFallback` 的 `rewrites` 参数签名略有差异，需要稍作调整。
• `import.meta.env`： 最初看 changelog 写已支持。我高兴地直接使用，却被回滚，只能回退到传统的 D​efinePlugin​`。

• Cold start: 从约 38 秒降到约 6 秒；感知提高不明显，但省下倒杯水的时间还是值得赞赏。
•  从约 400 ms 降到不到 100 ms；实打实的体感变化——改动几乎即时反馈，不再打断思路。
•  从两分钟降到约 15 秒；CI 建立时间显著缩短，使得 push 完即可部署，提高发布节奏。
•  从近 2 GB 降至约 600 MB；对 CI 节点资源压力明显减轻。

If your project is a legacy Webpack codebase with hundreds of modules and a build time of minutes。Rspack can bring a tangible boost. For us migration was worth it.

• If you’re still on Webpack 4,upgrade to Webpack 5 first—Rspack 对 v4 的 loader兼容性更差，迁移成本会高不少。
• If you already use Vite。re’s little reason to switch—Rspack 的优势在于平滑迁移存量 Webpack 项目，而不是与 Vite 同台竞争。说起来，
• A pre‑migration tip：先把现有 Webpack 配置理清楚。我们的 config 三年里被多人叠加，各种冗余 loader 层出不穷。趁迁移机会一次性清理，比把一份臃肿配置硬翻译成 Rspack 更省事。

• SWC 替换 Babel 时要显式声明目标 ECMAScript（如 'es2020') 和对应 parser，否则新特性会报错；JS 文件中的 decorators 要单独配置 parser = ‘ecmascript’。
• C‌SS Modules 在 Rspack 中有自己的内建实现，需要通过 .module.parser .localIdentName … 来自定义命名规则，而不是依赖外部 css‑loader 参数。
• P​lugin/loader 替换大多数可以“一键替换”，但仍需关注版本兼容、默认行为差异还有少数功能是否缺失或行为不同。
• Migrating 成功后你会得到更快的冷启动、更流畅的 HMR 与更低的资源使用情况——这正是“浪费生命”的 CI 队列所不愿看到的效果。其实，