Back to Details

migrate-to-rsbuild

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate to Rsbuild

迁移至 Rsbuild

Goal

目标

Migrate webpack, Vite, create-react-app (CRA/CRACO), or Vue CLI projects to Rsbuild with minimal behavior changes and clear verification.

将 webpack、Vite、create-react-app（CRA/CRACO）或 Vue CLI 项目迁移至 Rsbuild，确保行为变化最小化并完成清晰的验证。

Supported source frameworks

支持的源框架

webpack
Vite
CRA / CRACO
Vue CLI

webpack
Vite
CRA / CRACO
Vue CLI

Migration principles (must follow)

迁移原则（必须遵循）

Official guide first: treat Rsbuild migration docs as source of truth.
Smallest-change-first: complete baseline migration first, then migrate custom behavior.
Do not change business logic: avoid touching app runtime code unless user explicitly asks.
Validate before cleanup: keep old tool dependencies/config temporarily if needed; remove only after Rsbuild is green.

优先参考官方指南：将 Rsbuild 迁移文档作为权威依据。
优先最小化变更：先完成基线迁移，再迁移自定义行为。
请勿修改业务逻辑：除非用户明确要求，否则避免触碰应用运行时代码。
验证后再清理：如有需要，暂时保留旧工具的依赖/配置；仅在 Rsbuild 验证通过后再移除。

Workflow

工作流程

Detect source framework

Check

package.json

dependencies/scripts and config files:

webpack:
```
webpack.config.*
```
Vite:
```
vite.config.*
```
CRA/CRACO:
```
react-scripts
```
,
```
@craco/craco
```
,
```
craco.config.*
```
Vue CLI:
```
@vue/cli-service
```
,
```
vue.config.*
```

Apply framework-specific deltas

webpack:
```
references/webpack.md
```
Vite:
```
references/vite.md
```
CRA/CRACO:
```
references/cra.md
```
Vue CLI:
```
references/vue-cli.md
```

Validate behavior
- Run dev server to verify the project starts without errors.
- Run build command to verify the project builds successfully.
- If issues remain, compare the old project configuration with the migration guide and complete any missing mappings.
Cleanup and summarize
- Remove obsolete dependencies/config only after validation passes.
- Summarize changed files and any remaining manual follow-ups.

检测源框架
- 检查
```
package.json
```
  中的依赖/脚本以及配置文件：
  - webpack：
```
webpack.config.*
```
  - Vite：
```
vite.config.*
```
  - CRA/CRACO：
```
react-scripts
```
    、
```
@craco/craco
```
    、
```
craco.config.*
```
  - Vue CLI：
```
@vue/cli-service
```
    、
```
vue.config.*
```

应用框架专属迁移差异配置

webpack：
```
references/webpack.md
```
Vite：
```
references/vite.md
```
CRA/CRACO：
```
references/cra.md
```
Vue CLI：
```
references/vue-cli.md
```

验证行为
- 运行开发服务器，验证项目可正常启动且无错误。
- 运行构建命令，验证项目可成功构建。
- 若仍存在问题，对比旧项目配置与迁移指南，补全所有缺失的配置映射。
清理与总结
- 仅在验证通过后，移除过时的依赖/配置。
- 总结已修改的文件以及任何剩余的手动后续任务。