---

Rsbuild 入门指南：快速掌握高性能前端构建的利器

在现代前端开发领域，构建工具扮演着至关重要的角色。从代码编译、模块打包、资源优化到开发服务器，一个高效、易用的构建工具能够显著提升开发效率和最终产品的性能。近年来，随着项目复杂度的不断提升和开发者对极致性能的追求，基于 Rust 等高性能语言编写的新一代构建工具应运而生，Rsbuild 正是其中的佼佼者。

Rsbuild 是一个基于 Rspack 的高性能 Web 构建工具，旨在提供开箱即用的最佳实践和极致的构建速度。它由 Webpack 和 Modern.js Builder 背后的团队倾力打造，继承了 Webpack 强大的生态和灵活性，同时通过 Rspack (基于 Rust 的 Webpack 兼容打包器) 实现了数倍甚至数十倍的性能提升。本篇文章将作为一份详细的入门指南，带你一步步了解 Rsbuild 的核心理念、优势、基本用法和关键特性，助你快速掌握并将其应用于实际项目中。

为什么选择 Rsbuild？

在深入了解如何使用 Rsbuild 之前，我们先探讨一下为什么它值得你关注和尝试：

1. 极致的构建性能： 这是 Rsbuild 最核心的优势。得益于其底层基于 Rust 实现的 Rspack 内核，Rsbuild 在编译和打包速度上相比传统的 JavaScript 构建工具（如 Webpack）有了质的飞跃。无论是冷启动、热更新（HMR）还是生产环境构建，Rsbuild 都能显著缩短等待时间，尤其是在大型项目中，这种性能提升带来的体验改善尤为明显。Rust 的内存安全和并发能力使得 Rspack 能够高效地处理复杂的依赖关系和大量的模块。
2. 卓越的开发体验 (DX)： Rsbuild 不仅仅追求速度，也非常注重开发者的使用体验。它提供了：
   • 开箱即用： 内置了对 TypeScript、JSX、CSS、CSS Modules、Sass/Less、图片、字体等常见资源类型的支持，无需繁琐配置即可开始开发。
   • 快速热更新 (HMR)： 基于 Rspack 的增量编译能力，实现极速的模块热替换，让你在修改代码后几乎瞬间看到效果。
   • 清晰的错误提示： 优化的错误输出和堆栈信息，帮助开发者快速定位和解决问题。
   • 现代化的开发服务器： 功能完善且高效的开发服务器。
3. 灵活且简洁的配置： Rsbuild 遵循“约定优于配置”的原则，提供了合理的默认配置，满足大部分场景的需求。同时，它也暴露了强大的配置接口，允许开发者根据项目需求进行深度定制。其配置项设计相比 Webpack 更加简洁直观，易于理解和维护。
4. 丰富的插件生态： Rsbuild 拥有一个设计良好且易于扩展的插件系统。官方提供了众多高质量插件（如 React、Vue、Svelte 框架集成插件，SWC 或 Babel 编译切换插件等），社区也可以方便地开发自定义插件来满足特定需求。这使得 Rsbuild 能够适应各种复杂多变的项目场景。
5. Webpack 生态兼容性： 由于 Rspack 旨在与 Webpack 兼容，许多现有的 Webpack Loader 和 Plugin 理论上也可以在 Rsbuild (或 Rspack) 中使用，尽管可能需要一些适配或等待 Rspack 兼容层进一步完善。这为从 Webpack 迁移提供了可能性。
6. 面向未来的架构： 基于 Rust 构建意味着更好的性能潜力和对底层硬件资源的充分利用。随着 Web 技术的发展，Rsbuild 能够更好地应对未来的挑战。

与其他构建工具的简要对比：

• Vs Webpack: Rsbuild (基于 Rspack) 主要解决了 Webpack 的性能瓶颈，同时提供了更简洁的配置和更好的开箱即用体验。
• Vs Vite: Vite 以其基于原生 ES Modules 的极速冷启动开发服务器而闻名。Rsbuild 的开发服务器启动速度也很快，虽然机制不同（基于 Rspack 打包），但在 HMR 速度和生产构建速度方面，Rsbuild (Rspack) 通常更具优势，尤其是在大型项目中。Vite 使用 Rollup 进行生产构建，而 Rsbuild 使用 Rspack。两者在生态和侧重点上有所不同。Rsbuild 更强调与 Webpack 生态的兼容性和对大型复杂应用的构建优化。

准备工作

在开始使用 Rsbuild 之前，请确保你的开发环境中安装了以下软件：

• Node.js: Rsbuild 需要 Node.js 运行环境。建议安装 v16.0.0 或更高版本。你可以访问 Node.js 官网 下载并安装。
• 包管理器: 你需要一个包管理器来安装依赖，如 npm (通常随 Node.js 一起安装)、yarn 或 pnpm。本文示例将主要使用 npm。

你可以通过在终端运行以下命令来检查你的 Node.js 和 npm 版本：

bash
node -v
npm -v

快速上手：创建你的第一个 Rsbuild 项目

Rsbuild 提供了官方的脚手架工具 create-rsbuild，可以帮助你快速初始化一个 Rsbuild 项目。

1. 使用 create-rsbuild 创建项目:
   打开你的终端，运行以下命令：

   bash
npm create rsbuild@latest

   或者使用 yarn 或 pnpm：

   “`bash
   yarn create rsbuild@latest

   or

   pnpm create rsbuild@latest
   “`

2. 根据提示进行选择:
   脚手架会引导你进行一些选择：

   • Project Name: 输入你的项目名称（例如 my-rsbuild-app）。
   • Framework: 选择你想要使用的前端框架。Rsbuild 对 React 和 Vue 提供了内置支持，也可以选择 ‘Vanilla’ (原生 JS) 或其他框架（可能需要额外配置或插件）。这里我们以选择 ‘React’ 为例。

   脚手架会自动创建项目目录，并安装必要的依赖。

3. 进入项目目录:

   bash
cd my-rsbuild-app

4. 项目结构概览:
   创建完成后，你的项目目录结构大致如下 (以 React 模板为例)：

   my-rsbuild-app/
├── node_modules/ # 项目依赖
├── public/ # 静态资源目录 (会被直接复制到输出目录)
│ └── index.html # HTML 入口模板 (通常不需要，Rsbuild 会自动生成)
├── src/ # 源代码目录
│ ├── App.css # 示例 CSS
│ ├── App.tsx # 示例 React 组件
│ └── index.tsx # 应用入口文件
├── package.json # 项目信息和依赖管理
├── rsbuild.config.ts # Rsbuild 配置文件 (核心)
└── tsconfig.json # TypeScript 配置文件

   • rsbuild.config.ts: 这是 Rsbuild 的主要配置文件，我们稍后会详细介绍。
   • src/index.tsx: 这是应用程序的入口 JavaScript/TypeScript 文件。
   • public/: 此目录下的文件会被直接复制到最终的构建输出目录。通常用于放置不需要构建处理的静态资源，如 favicon.ico。Rsbuild 默认会自动生成 index.html，所以 public/index.html 一般是不需要的，除非你想完全自定义 HTML 模板。

核心命令

Rsbuild 项目通常在 package.json 的 scripts 字段中定义了几个核心命令：

• 启动开发服务器 (dev):
  在项目根目录下运行：

  bash
npm run dev

  或者使用 yarn 或 pnpm：

  “`bash
  yarn dev

  or

  pnpm dev
  “`

  此命令会启动一个本地开发服务器，并监听文件变化。它具有以下特点：
  * 快速启动： 基于 Rspack 的高效构建。
  * 热模块替换 (HMR)： 当你修改 src 目录下的代码时，浏览器会自动更新修改的部分，无需刷新整个页面，状态也会尽可能保留。
  * 实时预览： 在浏览器中打开指定的地址（通常是 http://localhost:3000 或类似地址）即可预览你的应用。
  * 友好的错误提示： 如果代码存在错误，会在终端和浏览器控制台中显示清晰的错误信息。

• 构建生产环境包 (build):
  当你准备将应用部署到生产环境时，运行：

  bash
npm run build

  或者使用 yarn 或 pnpm：

  “`bash
  yarn build

  or

  pnpm build
  “`

  此命令会执行生产环境构建，进行各种优化，生成用于部署的静态文件。主要优化包括：
  * 代码压缩： 使用高效的压缩器（如 SWC 或 Terser）减小 JavaScript 和 CSS 文件体积。
  * 代码分割 (Code Splitting)： 自动或根据配置将代码拆分成多个 chunk，实现按需加载，提升首屏性能。
  * Tree Shaking： 移除未使用的代码。
  * 静态资源优化： 处理图片、字体等资源，并可能进行优化。
  * 生成 Source Map： 便于在生产环境调试。

  构建完成后，所有优化过的静态资源会输出到默认的 dist 目录下。你可以将 dist 目录的内容部署到你的服务器或静态托管平台。

• 预览生产构建 (preview):
  有些模板可能还提供了 preview 命令：

  bash
npm run preview

  此命令会在本地启动一个简单的静态文件服务器，用于预览 build 命令生成的生产环境构建包，方便在部署前进行检查。

深入理解 Rsbuild 配置 (rsbuild.config.ts)

虽然 Rsbuild 强调开箱即用，但实际项目中往往需要进行一些定制化配置。rsbuild.config.ts 文件就是进行这些配置的核心。它使用 TypeScript 编写，提供了良好的类型提示和智能感知。

一个基本的 rsbuild.config.ts 文件结构如下：

“`typescript
import { defineConfig } from ‘@rsbuild/core’;
import { pluginReact } from ‘@rsbuild/plugin-react’; // 如果使用 React

export default defineConfig({
// 引入框架插件 (例如 React, Vue)
plugins: [pluginReact()],

// 源文件入口配置
source: {
entry: {
index: ‘./src/index.tsx’, // 定义入口文件，默认是 ‘./src/index.js’ 或 ‘./src/index.ts’
},
// 为目录设置别名，方便导入
alias: {
‘@’: ‘./src’,
‘@components’: ‘./src/components’,
},
},

// 开发服务器配置
dev: {
// 配置 HMR 行为、端口号等
port: 3000,
// … 其他 dev server 配置
},

// 生产环境构建输出配置
output: {
// 配置输出目录、资源文件名、代码分割规则等
distPath: {
root: ‘build’, // 修改输出目录为 ‘build’ 而不是默认的 ‘dist’
},
assetPrefix: ‘/static/’, // 配置静态资源 CDN 前缀
// … 其他 output 配置
},

// 工具链配置 (例如 SWC, Babel)
tools: {
// 配置 SWC 或 Babel 的编译选项
swc: {
// SWC 相关配置
},
// postcss, terser, htmlPlugin 等工具的配置
},

// 性能优化相关配置
performance: {
// 例如开启/关闭 chunk splitting, prefetch/preload 等
chunkSplit: {
strategy: ‘split-by-experience’, // 智能代码分割策略
},
},

// HTML 相关的配置
html: {
// 配置 HTML 标题、注入的 meta 标签、favicon 等
title: ‘My Awesome App’,
favicon: ‘./src/assets/favicon.ico’,
},

// CSS 相关配置
output: {
// … 省略其他 output 配置
cssModules: {
// 配置 CSS Modules 的行为，如 localIdentName
localIdentName: ‘[path][name]__[local]–[hash:base64:5]’,
},
},

// 安全相关配置 (例如 SRI)
security: {
sri: true, // 开启 Subresource Integrity
},

// 更多高级配置…
});
“`

defineConfig 是一个辅助函数，用于提供配置项的类型提示。Rsbuild 的配置项非常丰富，覆盖了从入口、输出、开发服务器、各种资源处理（JS/TS, CSS, Assets）、性能优化到插件管理的方方面面。

一些常用的配置场景示例：

1. 配置别名 (Alias):
   简化模块导入路径。

   typescript
export default defineConfig({
source: {
alias: {
'@': './src',
'@utils': './src/utils',
'@styles': './src/styles',
},
},
});
   之后你就可以这样导入模块：import MyComponent from '@/components/MyComponent';

2. 配置开发服务器代理 (Proxy):
   解决开发环境下的跨域请求问题。

   typescript
export default defineConfig({
dev: {
proxy: {
'/api': {
target: 'http://your-backend-api.com',
changeOrigin: true,
pathRewrite: { '^/api': '' }, // 可选：重写请求路径
},
},
},
});
   这样，所有发往 /api 的请求都会被代理到 http://your-backend-api.com。

3. 配置环境变量:
   Rsbuild 支持通过 source.define 配置编译时环境变量，或通过 .env 文件加载运行时环境变量。

   typescript
// rsbuild.config.ts
export default defineConfig({
source: {
define: {
'process.env.API_BASE_URL': JSON.stringify('https://api.example.com'),
},
},
});
   在代码中可以直接使用 process.env.API_BASE_URL。

4. 处理静态资源:
   Rsbuild 内置了对图片、字体等静态资源的处理。默认情况下，小于一定大小（如 10KB）的图片会被转换为 Base64 Data URL 内联到代码中，以减少 HTTP 请求；大于该阈值的文件则会被复制到输出目录，并在代码中引用其 URL。可以通过 output.dataUriLimit 调整这个阈值。

   typescript
export default defineConfig({
output: {
dataUriLimit: 8192, // 设置为 8KB
},
});

5. CSS 处理:
   Rsbuild 内置支持 CSS、CSS Modules、PostCSS、Less、Sass。

   • CSS Modules: 文件名以 .module.css (或 .module.less, .module.scss) 结尾的文件会自动启用 CSS Modules。可以通过 output.cssModules 进行配置。
   • PostCSS: 会自动应用 Autoprefixer。可以通过 tools.postcss 配置额外的 PostCSS 插件。
   • Sass/Less: 需要安装对应的预处理器依赖 (sass 或 less)。

Rsbuild 插件系统

插件是扩展 Rsbuild 功能的核心机制。Rsbuild 自身就大量使用了插件来提供各种内置功能。

• 使用插件:
  在 rsbuild.config.ts 的 plugins 数组中添加插件实例即可。

  “`typescript
  import { defineConfig } from ‘@rsbuild/core’;
  import { pluginReact } from ‘@rsbuild/plugin-react’;
  import { pluginImageCompress } from ‘@rsbuild/plugin-image-compress’; // 示例：图片压缩插件

  export default defineConfig({
  plugins: [
  pluginReact(), // 启用 React 支持
  pluginImageCompress(), // 启用图片压缩功能 (生产环境)
  ],
  // … 其他配置
  });
  “`

• 官方插件:
  Rsbuild 官方提供了一系列高质量插件，覆盖了常见需求：

  • @rsbuild/plugin-react: 集成 React 开发所需的热更新、JSX 编译等。
  • @rsbuild/plugin-vue: 集成 Vue 3 开发支持。
  • @rsbuild/plugin-vue2: 集成 Vue 2 开发支持。
  • @rsbuild/plugin-svelte: 集成 Svelte 开发支持。
  • @rsbuild/plugin-babel: 提供使用 Babel 进行代码编译的能力（可与 SWC 配合或替代）。
  • @rsbuild/plugin-type-check: 在构建时进行 TypeScript 类型检查。
  • @rsbuild/plugin-image-compress: 在生产构建时压缩图片资源。
  • @rsbuild/plugin-mdx: 支持 MDX 文件。
  • … 还有更多插件，可以在 Rsbuild 官方文档中查找。

• 开发自定义插件:
  Rsbuild 也提供了清晰的 Plugin API，允许开发者编写自己的插件来满足特定的构建需求，例如集成某个特殊的服务、执行自定义的构建步骤等。开发自定义插件需要对 Rsbuild 的生命周期和内部 API 有一定的了解。

性能优化的核心：Rspack

Rsbuild 的高性能主要归功于其底层的 Rspack。理解 Rspack 的一些关键特性有助于更好地利用 Rsbuild：

• Rust 语言优势: Rust 是一门以性能、内存安全和并发性著称的系统编程语言。用 Rust 重写 Webpack 的核心打包逻辑，避免了 Node.js 的一些性能开销（如 V8 引擎的 JIT 编译、垃圾回收等），并且能够更好地利用多核 CPU 进行并行处理。
• 与 Webpack 兼容: Rspack 的目标是尽可能兼容 Webpack 的配置和 Loader/Plugin API，使得从 Webpack 迁移到 Rsbuild/Rspack 更加平滑。虽然兼容性仍在不断完善中，但已经覆盖了大部分核心功能。
• 内置常用 Loader: Rspack 内置了许多常见文件类型的解析器（相当于 Webpack 的 Loader），例如 JavaScript、TypeScript、JSX、CSS 等，这些内置解析器同样用 Rust 实现，性能极高。这意味着在 Rsbuild 中，很多时候你不再需要像 Webpack 那样手动安装和配置大量的 Loader。
• 持续的性能优化: Rspack 团队持续在性能上进行投入，包括但不限于优化算法、改进缓存机制、利用更底层的系统能力等。

Rsbuild 的优势总结与展望

Rsbuild 结合了 Rspack 的极致性能和精心设计的上层封装，为前端开发者带来了全新的构建体验：

• 速度快： 大幅缩短开发和构建时间，提升开发效率。
• 易上手： 开箱即用，配置简洁，学习曲线相对平缓。
• 功能强： 内置丰富功能，插件生态完善，可扩展性强。
• 体验好： 快速 HMR、清晰错误提示，开发者体验优秀。

随着 Rspack 的不断成熟和 Rsbuild 生态的持续发展，它有望成为下一代前端项目构建的主流选择之一，尤其是在对性能有较高要求或项目规模较大的场景下。

下一步

• 阅读官方文档: Rsbuild 的官方文档 (https://rsbuild.dev/) 是最权威、最详细的学习资源，包含了完整的配置选项、插件列表、API 说明和迁移指南。
• 动手实践: 使用 create-rsbuild 创建一个项目，尝试修改配置、添加功能、运行构建，亲自体验 Rsbuild 的速度和易用性。
• 探索插件: 浏览官方插件列表，了解哪些插件可以帮助你解决特定的项目需求。
• 关注社区: 加入 Rsbuild 的社区（如 GitHub Discussions、Discord 等），与其他开发者交流，获取帮助，了解最新动态。

结语

Rsbuild 代表了前端构建工具发展的一个重要方向——追求极致性能与开发者体验的统一。通过拥抱 Rust 和 Rspack，它成功地突破了传统 JavaScript 构建工具的性能瓶颈，同时保持了良好的易用性和强大的扩展能力。如果你正苦于缓慢的 Webpack 构建，或者在寻找一个现代、高效且面向未来的构建方案，那么 Rsbuild 绝对值得你投入时间去学习和尝试。现在就开始，用 Rsbuild 为你的下一个项目注入强劲动力吧！

---