把 webpack 项目迁到 Rspack 2.0：依赖从 192 砍到 1，万组件构建缓存命中仅需 1.4s

背景：webpack 的老问题与 Rspack 的新答案

如果你的前端项目还在用 webpack 5，你大概率经历过这些痛点：

  • 生产构建慢：中大型项目动辄十几秒甚至几十秒，CI 流水线里构建步骤成了瓶颈。
  • 依赖臃肿：node_modules里塞满了间接依赖，webpack-dev-server一装就拉来上百个包。
  • HMR 不够快：改一行代码等一两秒才刷新，在万组件级项目里体验尤其明显。

字节跳动开源的Rspack从 1.0 开始就以「Rust 写的 webpack 替代品」定位进入开发者视野。2026 年 7 月 29 日，Rspack 团队正式发布了2.0 版本——这不再只是「更快一点的 webpack」，而是一次有意识的架构升级：默认行为向现代 JavaScript 开发对齐、核心包全面转为纯 ESM、默认依赖数量断崖式下降。

图0：文章封面（概念示意图）

官方在包含1 万个 React 组件的基准项目（rspack-react-10k-benchmark）上给出了如下数据：

版本生产构建（无缓存）生产构建（持久化缓存命中）HMR 热更新
Rspack 1.05.6 s5.6 s128 ms
Rspack 1.73.6 s2.2 s134 ms
Rspack 2.03.1 s1.4 s118 ms

数据来源：Rspack 2.0 官方发布博客。2.0 相比 1.7 整体性能提升约10%，相比 1.0 最多可提升100%。

图1：Rspack 官方 rspack-react-10k-benchmark 基准（1 万组件 React 项目）。数据为官方发布基准，非本文实测。

除了构建速度，2.0 另一个亮眼的改进是依赖精简：

包1.x 依赖数2.0 依赖数安装体积变化
@rspack/dev-server192115 MB →1.4 MB（>90%）
@rspack/core81——
@rspack/cli多个0——

图2：Rspack 2.0 默认依赖大幅精简（官方发布数据）。@rspack/cli在 2.0 变为零依赖且不再默认引入 dev-server。

本文将以一个真实的 webpack 5 项目为例，手把手走完迁移到 Rspack 2.0 的全流程，并标注每一步需要注意的坑点。

环境准备

Node.js 版本要求

Rspack 2.0 要求 Node.js ≥ 20.19 或 ≥ 22.12，不再支持 Node.js 18。这是相比 1.x 的重要变化，迁移前务必先确认：

node -v # 期望输出 v20.19.0+ 或 v22.12.0+

如果版本不满足，请先升级 Node.js。推荐使用 nvm（macOS/Linux）或 nvm-windows（Windows）管理多版本。

来源： Rspack 快速开始 —— 版本要求、 从 v1 升级到 v2

安装 Rspack 2.0

在项目目录下执行：

# 移除旧依赖 npm remove webpack webpack-cli webpack-dev-server 安装 Rspack 2.0（纯 ESM 包） npm add @rspack/core@^2.0.0 @rspack/cli@^2.0.0 -D 如果需要开发服务器（rspack dev / rspack serve） npm add @rspack/dev-server@^2.0.0 -D
注意：@rspack/cli和@rspack/dev-server在 2.0 中都是可选依赖。如果你只用rspack build做生产打包，不需要安装 dev-server。

第一步：替换 package.json 脚本

将构建脚本从 webpack 切换到 Rspack CLI：

{ "scripts": { "dev": "rspack dev", "build": "rspack build", "preview": "rspack preview" } }

Rspack CLI 支持与 webpack 类似的-c / --config参数指定配置文件。如果不指定，默认读取rspack.config.js（或.mjs）。

第二步：重命名并改造配置文件

将webpack.config.js重命名为rspack.config.mjs（推荐使用.mjs以匹配 2.0 的纯 ESM 生态），然后做以下关键改动：

2.1 缓存配置迁移

webpack 的cache.type: 'filesystem'在 Rspack 中对应cache.type: 'persistent'：

// rspack.config.mjs import { rspack } from '@rspack/core'; export default { // Rspack 持久化缓存 cache: { type: 'persistent', buildDependencies: [ import.meta.url, './package.json', ], }, };

开启持久化缓存后，二次构建（命中缓存）的速度会显著提升。官方数据显示 SWC 压缩插件的结果也可被缓存复用，缓存命中时构建性能再提升约50%，内存占用下降20%+。

2.2 用 builtin:swc-loader 替代 babel-loader

Rspack 内置了基于 SWC 的转译器，原生支持 TypeScript、JSX 和最新 ECMAScript 语法。如果你的babel-loader仅用于这些用途，可以直接移除：

// rspack.config.mjs export default { module: { rules: [ { test: /\.(?:js|mjs|jsx|ts|tsx)$/, loader: 'builtin:swc-loader', options: { detectSyntax: 'auto', jsc: { parser: { syntax: 'typescript', tsx: true, }, transform: { react: { runtime: 'automatic', }, }, }, }, }, ], }, };
如果你的 babel 配置包含自定义插件/预设（如 styled-components、i18n 等），则需要保留 babel-loader。但建议评估是否有 Rspack/SWC 原生替代方案，因为 babel-loader 在大项目中会显著拖慢构建速度。

2.3 插件替换映射

大部分 webpack 内置插件和社区插件可直接使用，但部分需要换成 Rspack 自带版本：

webpack 插件 / loaderRspack 2.0 替代
webpack.HotModuleReplacementPluginrspack.HotModuleReplacementPlugin
copy-webpack-pluginrspack.CopyRspackPlugin
mini-css-extract-pluginrspack.CssExtractRspackPlugin+CssExtractRspackPlugin.loader
css-loader保留不变（兼容）

示例——CSS 提取：

// rspack.config.mjs import { rspack } from '@rspack/core'; export default { plugins: [ new rspack.CssExtractRspackPlugin(), ], module: { rules: [ { test: /.css$/i, use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'], type: 'javascript/auto', }, ], }, };

第三步：处理破坏性变更

从 1.x 升级到 2.0 有若干不兼容变更需要逐一处理：

exportsPresence 默认值变更

module.parser.javascript.exportsPresence默认值从warn变为error。当代码引用了不存在的导出时，现在会直接报错而非仅警告：

// 如需恢复旧行为（不推荐长期使用） export default { module: { parser: { javascript: { exportsPresence: 'auto', }, }, }, };

devServer 部分选项变更

devServer.proxy、devServer.watchFiles等选项发生了变化。具体差异请查阅 升级指南 的「开发服务器」章节。

--analyze 已移除

@rspack/cli内置的webpack-bundler-analyzer已被移除，--analyze参数不可用。推荐使用Rsdoctor（Rspack 团队出的构建分析工具）替代：

npm add @rsdoctor/rspack-plugin -D

然后在配置中引入即可。

Pure ESM 包

@rspack/core、@rspack/cli、@rspack/dev-server在 2.0 中以纯 ESM形式发布，移除了 CommonJS 构建产物。Node.js 20+ 运行时已原生支持require(esm)加载 ESM 模块，所以通过 JavaScript API 使用 Rspack 的项目通常无需修改代码。但建议新配置文件统一使用import/export default语法。

第四步：完整迁移流程示意

以下是从头到尾的迁移步骤总览：

图3：webpack 5 → Rspack 2.0 迁移流程（概念示意）。实际操作中各步骤可能因项目复杂度有所调整。

第五步：测量验证

完成配置迁移后，用以下方式测量构建耗时：

# 无缓存完整构建 time rspack build 清除缓存后再测一次（确保冷启动） rm -rf node_modules/.cache/rspack time rspack build 再次构建（命中持久化缓存） time rspack build
以上命令输出的是你本地项目的实际数据，会因项目规模、硬件配置和插件组合而异。本文引用的 1.4s / 3.1s 等数字是 Rspack 官方在 1 万组件 React 基准项目上的测试结果，不代表你的项目一定能达到相同数值。

如果遇到构建错误，优先检查以下几点：

  1. Node.js 版本是否 ≥ 20.19。
  2. 是否遗漏了@rspack/dev-server的单独安装（使用rspack dev时必需）。
  3. 插件名是否已替换为rspack.*前缀版本。
  4. cache.type是否为'persistent'而非'filesystem'。

避坑清单

汇总迁移过程中最容易踩的坑：

#坑点解决方案
1Node 版本不够：升级后忘记查 Node 版本，直接npm install报错先执行node -v，确保 ≥ 20.19 / 22.12
2dev-server 找不到：rspack dev报Cannot find module '@rspack/dev-server'2.0 中 cli 不再默认依赖 dev-server，需手动npm add @rspack/dev-server -D
3cache 字段照搬：复制 webpack 的filesystem配置导致缓存不生效改为cache: { type: 'persistent' }
4babel-loader 拖慢速度：迁移后保留了不必要的 babel-loaderTS/JSX/ESNext 交给builtin:swc-loader，仅在确实需要 Babel 插件时保留
5exportsPresence 报错：之前只是 warn 的导出引用问题变成 error显式设为'auto'或修复源码中的无效导入
6--analyze 失效：习惯性加--analyze参数发现报错改用 Rsdoctor（@rsdoctor/rspack-plugin）
7.swcrc 不再读取：builtin:swc-loader在 2.0 中不再自动读.swcrc文件将 SWC 配置写入 loader 的options字段
8CommonJS 配置文件失效：旧的module.exports = {...}在某些场景下与纯 ESM 包冲突配置文件改用.mjs+export default {}

总结与延伸

Rspack 2.0 的核心价值可以概括为三件事：

  1. 构建更快：在官方万组件基准上，缓存命中后的生产构建降至1.4s，HMR118ms。
  2. 依赖更轻：dev-server 从 192 个依赖砍到1 个，安装体积缩减90%+。
  3. 生态更现代：纯 ESM、更合理的默认值、渐进式的 breaking change 管理。

对于从 webpack 5 迁移的存量项目，上述流程可以在一两个工时内完成主体工作。对于全新项目，Rspack 团队更推荐使用上层的Rsbuild（零配置构建工具，基于 Rspack，开箱即用）：

# 新项目推荐：用 Rsbuild（内置 Rspack 2.0） npm create rsbuild@latest

适用场景参考：

  • ✅ 适合迁移：React/Vue/Angular 的 webpack 5 项目、需要精细控制构建配置的中大型项目、CI 构建时间敏感的项目。
  • ⚠️ 暂不适合：重度依赖 V8 原生 addon（.node文件）的项目、Node.js < 20.19 的老旧环境、需要--analyze内置功能但未接入 Rsdoctor 的团队。

延伸阅读：

  • Rspack 2.0 官方发布博客（中文）
  • 从 webpack 迁移到 Rspack 官方指南
  • 从 Rspack 1.x 升级到 2.0（破坏性变更清单）
  • Rspack GitHub 仓库（MIT 协议，ByteDance Web Infra 团队维护）
  • Rsdoctor 构建分析工具
  • Rsbuild 零配置构建工具