从Modern.js Builder迁移到Rsbuild的完整指南

从Modern.js Builder迁移到Rsbuild的完整指南

前言

Rsbuild作为Modern.js Builder的下一代版本，在性能、功能和开发体验上都有了显著提升。本文将详细介绍如何将现有项目从Modern.js Builder平滑迁移到Rsbuild，帮助开发者充分利用Rsbuild的新特性。

Rsbuild的核心优势

Rsbuild相比Modern.js Builder具有以下显著优势：

1. 性能飞跃：采用Rspack作为默认打包工具，启动和构建速度提升1.5-2倍
2. 架构精简：专注于Rspack集成，去除对webpack的支持，减少维护成本
3. 功能增强：CLI工具和开发服务器支持更多现代化功能
4. 框架解耦：不与特定UI框架绑定，支持更灵活的项目配置

迁移步骤详解

1. 依赖替换

首先需要替换项目中的npm依赖项：

# 移除旧版Builder相关依赖
npm uninstall @modern-js/builder-cli @modern-js/builder-webpack-provider @modern-js/builder-rspack-provider

# 安装Rsbuild核心包
npm install @rsbuild/core -D

2. 脚本更新

修改package.json中的npm脚本，使用Rsbuild提供的命令：

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

注意变化：

• builder dev → rsbuild dev
• builder build → rsbuild build
• builder serve → rsbuild preview

3. 配置文件改造

将Builder配置文件迁移为Rsbuild格式：

1. 重命名文件：builder.config.ts → rsbuild.config.ts
2. 更新导入路径：

   import { defineConfig } from '@rsbuild/core';
   

3. 字段变更：
   • builderPlugins → plugins

完整示例：

import { defineConfig } from '@rsbuild/core';

export default defineConfig({
  plugins: [], // 插件数组
  // 其他配置...
});

4. 插件系统迁移

Rsbuild采用了全新的插件系统，需要替换原有的Builder插件：

| 原Builder插件 | 对应Rsbuild插件 | 备注 | |----------------------------------|---------------------------------|-----------------------------| | @modern-js/builder-plugin-vue | @rsbuild/plugin-vue | Vue项目必备 | | @modern-js/builder-plugin-vue2 | @rsbuild/plugin-vue2 | Vue 2.x项目专用 | | @modern-js/builder-plugin-stylus | @rsbuild/plugin-stylus | Stylus预处理支持 | | @modern-js/builder-plugin-swc | 无需配置(默认启用) | Rsbuild内置SWC支持 |

以Vue项目为例，迁移后配置：

import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
  plugins: [pluginVue()],
});

5. 框架相关配置

Rsbuild不再默认集成React支持，需要显式添加：

import { pluginReact } from '@rsbuild/plugin-react';

export default {
  plugins: [pluginReact()],
};

如果项目中使用SVGR，还需要单独配置：

import { pluginSvgr } from '@rsbuild/plugin-svgr';

export default {
  plugins: [pluginSvgr()],
};

重要配置变更

Rsbuild对部分默认配置进行了优化调整：

1. 浏览器兼容性：默认支持原生ES Modules的现代浏览器
2. 输出结构：HTML文件默认输出到dist根目录
3. Polyfill策略：按需注入，减少包体积
4. 类型检查：默认关闭，需要时通过插件启用

验证与调试

完成迁移后，建议按以下步骤验证：

1. 开发环境验证：

   npm run dev
   

2. 生产构建测试：

   npm run build && npm run preview
   

3. 检查控制台输出和页面功能

如遇问题，可参考Rsbuild文档或根据错误日志进行针对性调试。

总结

通过本文的步骤，开发者可以系统性地将项目从Modern.js Builder迁移到Rsbuild。Rsbuild在保持配置兼容性的同时，提供了更优异的性能和更现代化的功能支持。对于大型项目，建议分阶段逐步迁移，确保项目稳定性。

迁移过程中如遇到特殊场景，可查阅Rsbuild官方文档获取更多高级配置方案。