Rsbuild

基于 Rspack 的零配置高性能 Web 构建工具

技术简介说明

Rsbuild 是由字节跳动 Web Infra 团队开发的现代化 Web 构建工具，底层基于 Rspack（Rust 实现的高性能模块打包器）构建。它的定位类似于 webpack-cli + create-react-app 的结合体——既提供了开箱即用的零配置构建能力，又保留了完整的配置灵活性和可扩展性。Rsbuild 是 Rstack 统一 JavaScript 工具链的核心组件，同属该工具链的还有 Rspress（文档工具）、Rslib（库构建工具）、Rstest（测试框架）、Rsdoctor（调试工具）和 Rslint（代码检查工具）。

Rsbuild 的核心价值在于性能与易用性的统一。传统 Webpack 项目面临构建速度慢、配置复杂度高两大痛点，而 Vite 虽然通过 ESM 开发服务器解决了开发体验问题，但在大型项目的生产构建中仍有性能瓶颈。Rsbuild 通过 Rspack 的 Rust 引擎实现了与 esbuild 相当甚至更快的构建速度，同时通过合理的默认配置让开发者无需编写任何配置即可启动项目。自 1.0 发布以来，Rsbuild 的 npm 周下载量增长了超过 15 倍，已成为 Rspack 生态中最活跃的上层构建工具。

Rsbuild 2.0 于 2026 年 4 月发布，是一次重大的架构升级。它集成了 Rspack 2.0 引擎，带来了更快的构建速度和新的输出优化能力；转为纯 ESM 包，移除了 CommonJS 产物；默认 Node.js 目标版本从 16 升级到 20；依赖从 13 个精简到 4 个（减少约 2 MB）。2026 年 6 月发布的 2.1 版本进一步引入了基于 Rust 的 React Compiler（比 Babel 插件快 7-13 倍）、TanStack Start 集成和 Tailwind CSS v4 插件支持。

基本信息

快速上手

安装

使用 create-rsbuild 脚手架工具快速创建项目：

# pnpm（推荐）
pnpm create rsbuild@latest
 
# npm
npm create rsbuild@latest
 
# yarn
yarn create rsbuild
 
# bun
bun create rsbuild@latest
 
# deno
deno init --npm rsbuild@latest

脚手架会引导你选择框架模板和可选工具：

框架模板：

每个模板均提供 JavaScript 和 TypeScript 变体（如 react-js、react-ts、vue-js、vue-ts）。

可选工具（通过方向键和空格选择）：

• Rstest — 单元测试框架
• Rslint / ESLint — 代码检查
• Prettier / Biome — 代码格式化（Biome 同时支持 lint 和格式化）
• Storybook — 组件开发环境
• Tailwind CSS — 原子化 CSS 框架
• React Compiler — React 性能优化（仅 React 模板）

非交互式创建（用于 CI 或自动化）：

npx -y create-rsbuild@latest my-app -t react --tools eslint,prettier

在已有项目中手动安装：

pnpm add -D @rsbuild/core

基础配置

创建完成后，项目的核心配置文件为 rsbuild.config.ts：

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'
 
export default defineConfig({
  // 插件配置
  plugins: [pluginReact()],
 
  // 入口配置
  source: {
    entry: {
      index: './src/index.tsx',
      // 多入口
      admin: './src/admin/index.ts',
    },
    // 环境变量注入
    define: {
      'process.env.APP_VERSION': JSON.stringify('1.0.0'),
    },
  },
 
  // HTML 模板配置
  html: {
    title: 'My App',
    template: './src/index.html',
    favicon: './public/favicon.ico',
  },
 
  // 输出配置
  output: {
    // 输出目录
    distPath: {
      root: 'dist',
      js: 'static/js',
      css: 'static/css',
    },
    // 资源内联阈值（字节）
    dataUriLimit: {
      image: 8 * 1024,
      font: 8 * 1024,
      media: 8 * 1024,
    },
    // 自动外部依赖（读取 package.json，SSR 场景常用）
    autoExternal: true,
    // Source Map 策略
    sourceMap: {
      js: 'source-map',
      css: true,
    },
  },
 
  // 开发服务器配置
  server: {
    port: 3000,
    host: 'localhost',
    // 代理配置
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        pathRewrite: { '^/api': '' },
      },
    },
  },
 
  // 性能配置
  performance: {
    // chunk 分割策略
    chunkSplit: {
      strategy: 'split-by-size',
      minSize: 30_000,
      maxSize: 500_000,
    },
  },
})

package.json 中的脚本配置：

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

• rsbuild dev — 启动开发服务器，默认 http://localhost:3000
• rsbuild build — 创建生产构建产物
• rsbuild preview — 本地预览生产构建结果

最小示例

一个最简单的 Rsbuild 项目结构：

my-rsbuild-app/
├── src/
│   ├── index.ts        # 入口文件（自动检测 src/index.*）
│   ├── index.html      # HTML 模板（可选，Rsbuild 自动生成）
│   ├── App.tsx         # 应用组件
│   └── index.css       # 全局样式
├── rsbuild.config.ts   # 配置文件
├── tsconfig.json       # TypeScript 配置（可选）
└── package.json

src/App.tsx：

import './index.css'
 
export function App() {
  return (
    <div className="app">
      <h1>Hello Rsbuild!</h1>
      <p>基于 Rspack 的零配置高性能构建工具</p>
    </div>
  )
}

src/index.css：

.app {
  font-family: system-ui, -apple-system, sans-serif;
  text-align: center;
  padding: 2rem;
}
 
.app h1 {
  color: #165dff;
}

src/index.ts（入口文件）：

import { createRoot } from 'react-dom/client'
import { App } from './App'
 
const root = createRoot(document.getElementById('root')!)
root.render(<App />)

Rsbuild 会自动检测 src/index.(ts|js|tsx|jsx|mts|cts|mjs|cjs) 作为入口，自动生成 HTML 模板并注入脚本和样式，无需手动编写 index.html。

运行以下命令即可启动开发：

pnpm install
pnpm dev    # 启动开发服务器 → http://localhost:3000

核心概念与架构

Rspack 核心引擎

Rsbuild 的底层是 Rspack——一个用 Rust 实现的 JavaScript 打包器，与 Webpack 共享相同的配置生态（支持大部分 Webpack 插件和 Loader）。Rspack 的 Rust 实现带来了数量级的性能提升：

┌─────────────────────────────────────────────────┐
│                  用户代码                         │
│         (TS/JSX/CSS/Images/...)                 │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│              Rsbuild (配置层)                     │
│  ┌───────────┬───────────┬───────────────────┐  │
│  │ 插件系统   │ 配置合并   │  默认优化策略      │  │
│  └───────────┴───────────┴───────────────────┘  │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│            Rspack (打包引擎 · Rust)               │
│  ┌──────────────────────────────────────────┐   │
│  │ SWC (编译) │ LightningCSS │ 模块解析     │   │
│  │ 增量构建    │ 并行处理      │ 缓存系统     │   │
│  └──────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│              产物输出 (dist/)                     │
│    JS bundles / CSS / Assets / HTML              │
└─────────────────────────────────────────────────┘

Rspack 的核心性能优势：

• SWC 编译：替代 Babel，JS/TS/JSX 编译速度比 Babel 快 20-70 倍
• LightningCSS：替代 PostCSS + cssnano，CSS 处理性能提升 10-100 倍
• 并行架构：充分利用多核 CPU
• 持久缓存：增量构建只处理变更模块

配置分层体系

Rsbuild 的配置采用分层设计，优先级从高到低：

1. CLI 参数 — rsbuild build --minify false（最高优先级）
2. rsbuild.config.ts — 项目配置文件
3. 插件配置 — 通过 plugins 引入的配置
4. 默认配置 — Rsbuild 内置的零配置默认值（最低优先级）

import { defineConfig } from '@rsbuild/core'
 
export default defineConfig({
  // 第 1 层：Rsbuild 语义化配置
  source: {
    entry: { index: './src/index.ts' },
  },
 
  // 第 2 层：Rspack 配置覆盖
  tools: {
    rspack(config) {
      // 直接修改 Rspack 配置
      config.resolve ??= {}
      config.resolve.alias = {
        ...config.resolve.alias,
        '@utils': './src/utils',
      }
    },
  },
})

这种分层设计使得：

• 大部分项目无需任何配置即可运行
• 插件可以在不侵入用户配置的情况下增强能力
• 用户只需要覆盖真正需要调整的部分
• 高级用户可以通过 tools.rspack 访问底层打包器的完整能力

插件系统

Rsbuild 提供了一套轻量级但强大的插件系统。插件可以：

• 修改 Rsbuild 配置（modifyRsbuildConfig）
• 修改 Rspack 配置（modifyBundlerChain）
• 注册自定义 Loader 和 Plugin
• 钩入构建生命周期的各个阶段

import type { RsbuildPlugin } from '@rsbuild/core'
 
const myPlugin: RsbuildPlugin = {
  name: 'my-plugin',
 
  setup(api) {
    // 修改 Rsbuild 配置
    api.modifyRsbuildConfig((config) => {
      config.source ??= {}
      config.source.entry = { index: './src/main.ts' }
      return config
    })
 
    // 修改 Rspack 配置（通过 webpack-chain 风格 API）
    api.modifyBundlerChain((chain) => {
      chain.resolve.alias.set('@', api.context.rootPath)
      chain.plugin('my-plugin').use(MyWebpackPlugin)
    })
 
    // 钩入构建生命周期
    api.onBeforeBuild(() => {
      console.log('构建开始...')
    })
 
    api.onAfterBuild(({ stats }) => {
      console.log('构建完成', stats?.toString())
    })
  },
}

Environments API

Rsbuild 2.0 引入了 Environments API，支持在同一项目中为不同目标环境配置独立的构建参数。这对于 SSR 场景（同时构建客户端和服务端代码）特别有用：

import { defineConfig } from '@rsbuild/core'
 
export default defineConfig({
  environments: {
    web: {
      source: {
        entry: { index: './src/client/index.ts' },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        entry: { server: './src/server/index.ts' },
      },
      output: {
        target: 'node',
      },
    },
  },
})

Build 流水线

Rsbuild 的构建流水线分为以下阶段：

源码输入
  │
  ├── 1. 配置合并 — 合并用户配置、插件配置和默认配置
  │
  ├── 2. 环境解析 — 确定构建目标环境（web / node / web-worker）
  │
  ├── 3. 模块解析（resolve）
  │     └── 路径别名、条件导出、外部依赖
  │
  ├── 4. 转译处理（transform）
  │     └── SWC / Babel / Lightning CSS 处理源码
  │
  ├── 5. 模块打包（bundle）
  │     └── 依赖图构建、代码分割、Chunk 生成
  │
  ├── 6. 优化压缩（optimize）
  │     └── Tree Shaking、Scope Hoisting、压缩
  │
  └── 7. 产物输出（emit）
        └── 写入 dist/、生成 HTML、生成 Source Map

Dev Server

Rsbuild 内置开发服务器，提供完整的开发体验：

export default defineConfig({
  server: {
    port: 3000,
    host: 'localhost',
    // 代理配置（基于 http-proxy-middleware v4）
    proxy: {
      '/api': {
        target: 'http://backend:8080',
        changeOrigin: true,
        pathRewrite: { '^/api': '' },
      },
    },
    // 2.0 新增：服务器启动时运行初始化逻辑
    setupMiddlewares: (middlewares, server) => {
      middlewares.push((req, res, next) => {
        console.log(`${req.method} ${req.url}`)
        next()
      })
    },
  },
})

核心特性

1. 零配置启动

Rsbuild 的设计理念是"约定优于配置"，新项目无需任何配置即可启动：

pnpm create rsbuild@latest
cd my-project
pnpm dev        # 启动开发服务器
pnpm build      # 生产构建
pnpm preview    # 预览构建产物

开箱即用的能力包括：

• TypeScript 编译（基于 SWC）
• JSX/TSX 支持（React 自动 runtime）
• CSS Modules（自动识别 .module.css）
• 静态资源处理（图片、字体、媒体文件）
• HTML 模板生成与脚本注入
• Source Map（开发模式含行列映射）
• 代码分割（默认按经验策略拆分）
• 生产环境压缩（SWC Minifier）
• 自动检测入口文件

2. Rspack 极致性能

基于 Rspack 的 Rust 引擎，Rsbuild 在各项性能指标上表现出色：

以上为典型中型项目（~1000 模块）的参考数据，实际结果因项目而异。

3. 内置 TypeScript / JSX / CSS 支持

Rsbuild 内置了对现代 Web 技术栈的全面支持，无需额外安装和配置：

• TypeScript — 通过 SWC 转译，支持类型检查（可选 plugin-type-check）
• JSX / TSX — 自动检测和处理，支持 React、Vue、Preact 等框架的 JSX
• CSS — 支持 CSS Modules、CSS 预处理器（Sass / Less / Stylus）、PostCSS
• CSS 新特性 — 支持 Lightning CSS 处理 CSS 降级和特性转换
• 装饰器 — 支持 TC39 Decorators（2023-11 版本，2.0 起更新）

// 自动识别 .ts/.tsx/.js/.jsx 文件，无需写扩展名
import { helper } from './utils/helper'
import type { User } from '@/types/user' // 类型导入自动擦除
 
// JSX 自动 runtime（React 17+），无需 import React
const App = () => <div>Hello</div>

4. 轻量级插件系统

Rsbuild 的插件系统设计简洁而强大：

• 基于 setup 函数的插件模型
• 提供丰富的生命周期钩子
• 兼容 Rspack 插件和大部分 Webpack 插件
• 官方提供高质量的框架插件
• 社区插件通过 npm 关键词 rsbuild-plugin 搜索

5. 多框架支持

Rsbuild 是框架无关的，通过官方插件支持多种前端框架：

React 插件还支持 React Server Components（通过 rsbuild-plugin-rsc）。

6. 资源处理与优化

Rsbuild 自动处理各类静态资源，并提供智能优化：

• 图片 — 自动内联小图片（默认阈值可配置），大图片独立输出并添加 content hash
• 字体 — 支持 WOFF / WOFF2 / TTF / OTF 等格式
• SVG — 支持作为 URL 引用或 React 组件（通过 plugin-svgr）
• WebAssembly — 2.1 新增 import source 语法支持，直接访问 WebAssembly.Module
• YAML / TOML — 通过对应插件支持配置文件格式
• CSS ?url 导入 — 2.1 新增，获取编译后 CSS 文件的 URL，适用于微前端动态样式加载

// 小于 dataUriLimit 的资源自动内联为 Data URL
import logo from './logo.png'    // → Data URL 或文件路径
import bg from './bg.jpg'        // → 文件路径（带 content hash）
import icon from './icon.svg'    // → 文件路径

7. 开发服务器

内置的开发服务器提供了完整的开发体验：

• HMR（热模块替换） — 基于 Rspack 增量编译，毫秒级更新（~160ms）
• Fast Refresh — React 组件热更新（保持状态）
• WebSocket 通信 — 2.0 新增，支持通过 hot.send 从服务端向客户端发送消息
• 代理配置 — 基于 http-proxy-middleware v4（httpxy 后端）
• HTTPS 支持 — 内置 HTTPS 配置
• 自定义启动逻辑 — 2.0 新增 server.setup，在服务器启动时运行初始化代码
• 自定义 Logger — 2.0 新增，支持按实例定义不同级别和前缀的日志
• 多页面支持 — 自动识别多入口并生成对应 HTML

8. 生产优化

Rsbuild 内置了丰富的生产环境优化策略：

• Tree Shaking — 基于 ESM 的静态分析，自动移除未使用代码
• 代码分割 — 支持多种策略：split-by-experience（默认）、split-by-size、per-package、all-in-one 等
• 资源压缩 — 内置 JavaScript / CSS / HTML 压缩（SWC Minifier）
• 资源指纹 — 自动为文件名添加 content hash（长期缓存）
• Scope Hoisting — 模块合并减少运行时开销
• 自动外部依赖 — 2.1 新增 output.autoExternal，读取 package.json 自动生成 external 规则

export default defineConfig({
  output: {
    chunkSplit: {
      strategy: 'split-by-experience',  // 默认：按经验拆分
    },
    sourceMap: {
      js: false,  // 生产环境关闭 JS Source Map
    },
  },
  performance: {
    removeConsole: true,  // 移除 console.log
    printFileSize: true,  // 打印文件大小
  },
})

9. 稳定的构建产物

Rsbuild 承诺构建产物的稳定性——相同输入在相同配置下产生相同的输出。这对于 CDN 缓存和增量部署非常重要。Rspack 引擎确保了构建行为的确定性和可预测性。

10. Worker 和微前端支持

• Web Workers — 2.1 新增，支持通过 ?worker 查询语法导入 Worker，支持 inline 选项
• Module Federation — 支持 Rspack 的 Module Federation 插件，适用于微前端场景
• CSS ?url 导入 — 获取编译后 CSS 文件的 URL，适用于微前端动态样式加载
• 并行处理 — 2.1 新增，Babel 和 SVGR 插件支持 parallel 选项，通过 Worker 线程分发工作

生态图

官方核心插件

@rsbuild/core                    # 核心包，提供 CLI 和 JavaScript API
├── @rsbuild/plugin-react        # React 支持（含 React Compiler）
├── @rsbuild/plugin-vue          # Vue 3 支持
├── @rsbuild/plugin-vue2         # Vue 2 支持
├── @rsbuild/plugin-svelte       # Svelte 支持
├── @rsbuild/plugin-solid        # Solid 支持
├── @rsbuild/plugin-preact       # Preact 支持
├── @rsbuild/plugin-lit          # Lit 支持
├── @rsbuild/plugin-babel        # Babel 转译（支持并行处理）
├── @rsbuild/plugin-sass         # Sass 预处理器
├── @rsbuild/plugin-less         # Less 预处理器
├── @rsbuild/plugin-stylus       # Stylus 预处理器
├── @rsbuild/plugin-tailwindcss  # Tailwind CSS v4 支持
├── @rsbuild/plugin-image-compress # 图片压缩
├── @rsbuild/plugin-svgr         # SVG 转 React 组件
├── @rsbuild/plugin-yaml         # YAML 文件支持
├── @rsbuild/plugin-toml         # TOML 文件支持
├── @rsbuild/plugin-type-check   # TypeScript 类型检查
├── @rsbuild/plugin-source-build # Monorepo 源码构建
├── @rsbuild/plugin-node-polyfill # Node.js Polyfill
└── rsbuild-plugin-rsc           # React Server Components 支持

Rstack 工具链

Rstack（统一 JavaScript 工具链）
├── Rspack     # Rust 实现的模块打包器（底层引擎）
├── Rsbuild    # 零配置构建工具（本文主角）
├── Rslib      # 库/包构建工具（输出 ESM/CJS/UMD）
├── Rspress    # 文档站点生成器
├── Rstest     # 测试框架
├── Rsdoctor   # 构建调试与分析工具
└── Rslint     # 代码检查工具

社区生态

• rsbuild-plugin-angular — Angular 支持（社区维护）
• rsbuild-plugin-react-router — React Router 集成
• @nx/rsbuild — Nx Monorepo 集成（提供 generators 和 executors）
• Turborepo 官方指南支持 Rsbuild 应用和 Module Federation

社区插件可通过 npm 关键词 rsbuild-plugin 搜索，更多资源见 awesome-rstack。

适用场景

1. 新项目快速启动

Rsbuild 的零配置特性使其成为新项目的理想选择。通过 pnpm create rsbuild@latest 可以在几秒钟内创建一个配置完善的项目，包括 TypeScript 支持、HMR、代码分割、资源优化等。脚手架还支持在创建时选择 ESLint、Prettier、Tailwind CSS、Storybook 等工具，一步到位搭建完整开发环境。

pnpm create rsbuild@latest --template react-ts
# 即得：TypeScript + React + HMR + 生产优化，开箱即用

2. Webpack 项目迁移

Rsbuild 兼容大部分 Webpack 插件和 Loader，为从 Webpack 迁移提供了平滑路径。由于底层共享 Rspack 的配置模型，很多 Webpack 配置可以直接复用或只需小幅调整：

export default defineConfig({
  tools: {
    rspack: {
      // Rspack 兼容大部分 Webpack 配置
      // 可直接迁移 module.rules → module.rules
    },
  },
})

官方提供了详细的 Webpack 迁移指南。

3. Create React App / Vue-CLI 迁移

随着 CRA 和 Vue-CLI 停止维护，大量项目需要迁移到现代构建工具。Rsbuild 提供了专门的迁移指南：

• CRA 迁移 — 保留 React 生态兼容性，提供更好的开发体验和构建速度
• Vue-CLI 迁移 — 支持 Vue 2 和 Vue 3 项目，保持配置兼容性

4. 多框架项目

Rsbuild 的框架无关设计使其适合需要同时使用多种框架的项目。通过 Environments API，可以在同一个项目中为 React 组件、Vue 组件分别配置独立的构建环境，共享统一的构建基础设施。

5. 组件库开发

结合 Rslib（基于 Rsbuild 的库构建工具），Rsbuild 适合用于开发组件库和 npm 包。Rslib 支持输出 ESM / CJS / UMD 多种格式，配合 Rsbuild 的插件系统可以处理样式、类型声明、资源文件等。

pnpm create rslib@latest
# 支持 ESM/CJS/UMD 多格式输出
# 内置 TypeScript 声明文件生成

6. Monorepo 构建

Rsbuild 原生支持 Monorepo 工作流：

• Nx 集成 — @nx/rsbuild 提供 generators 和 executors
• Turborepo 支持 — 官方文档提供了 Turborepo + Rsbuild 的配置指南
• Module Federation — 支持微前端架构下的 Monorepo 构建
• plugin-source-build — 自动识别 monorepo 中的本地包并源码构建

7. SSR 与全栈应用

通过 Environments API 和 output.autoExternal，Rsbuild 可以方便地配置 SSR 构建。结合 TanStack Start（2.1 起官方支持）或 Modern.js 等全栈框架，可以获得开箱即用的 SSR 体验。Rsbuild 2.0 的 React Server Components 插件进一步扩展了 SSR 能力。

开发与工程化

开发流程

# 开发模式
pnpm dev          # 启动 Dev Server（默认 http://localhost:3000）
 
# 构建
pnpm build        # 生产构建 → dist/
pnpm build:dev    # 开发模式构建（含 Source Map）
 
# 预览
pnpm preview      # 本地预览 dist/
 
# CLI 高级选项
rsbuild build --environment web    # 指定环境构建
rsbuild inspect                    # 检查最终配置
rsbuild dev --port 8080            # 指定端口
rsbuild dev --config ./custom.config.ts  # 指定配置文件

环境变量

Rsbuild 支持通过 .env 文件管理环境变量，按优先级加载：

.env.[mode].local    （最高，git 忽略）
.env.[mode]          （mode = development | production）
.env.local           （git 忽略）
.env                 （基准）

# .env
RSBUILD_APP_TITLE=My App
RSBUILD_API_URL=https://api.example.com
CUSTOM_VAR=will-not-expose    # 不以 RSBUILD_ 开头的不会暴露到代码中

// 在代码中使用
console.log(process.env.RSBUILD_APP_TITLE)  // → "My App"
 
// 在 rsbuild.config.ts 中使用（函数形式）
export default defineConfig(({ env, command }) => {
  const isProd = env === 'production'
  return {
    source: {
      define: {
        __DEV__: JSON.stringify(!isProd),
      },
    },
  }
})

CI/CD 集成

GitHub Actions 示例：

name: Build and Deploy
on:
  push:
    branches: [main]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

非交互式创建项目（用于 CI）：

npx -y create-rsbuild@latest my-app \
  --template react-ts \
  --tools eslint,prettier,tailwindcss \
  --dir ./my-app

Docker 部署

多阶段 Docker 构建示例：

# 构建阶段
FROM node:22-alpine AS builder
WORKDIR /app
RUN corepack enable && corepack prepare pnpm@latest --activate
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
 
# 运行阶段
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

性能与安全

Rspack 性能优势

Rsbuild 的性能优势来源于 Rspack 的 Rust 实现：

Rspack 使用 Rust 实现了 Webpack 的核心打包逻辑，同时集成了 SWC（替代 Babel）和 Lightning CSS（替代 PostCSS），在转译和样式处理环节也获得了 Rust 级别的性能。

缓存策略

Rsbuild 利用 Rspack 的持久化缓存机制加速二次构建：

export default defineConfig({
  performance: {
    buildCache: {
      enable: true,
      cacheDirectory: './node_modules/.cache/rspack',
      cacheDigest: [
        // 自定义缓存哈希因子
      ],
    },
  },
})

缓存存储在 node_modules/.cache 目录中，可以显著减少重复构建的时间。

Tree Shaking

Rsbuild 内置了完善的 Tree Shaking 支持：

• ESM 静态分析 — 基于 import / export 语句的静态分析
• Side Effects 标记 — 支持 package.json 的 sideEffects 字段
• Module Concatenation — 模块合并减少运行时开销
• Dead Code Elimination — 移除不可达代码

// ✅ 可被 Tree Shake（ESM 模块）
import { debounce } from 'lodash-es'  // 只保留 debounce
 
// ❌ 无法 Tree Shake（CJS 模块）
import _ from 'lodash'                // 整个 lodash 都会被打入

安全特性

• 默认绑定 localhost — 2.0 起默认 host 从 0.0.0.0 改为 localhost，避免意外暴露到局域网
• 代理中间件升级 — 使用 http-proxy-middleware v4（httpxy 后端），修复了已知安全问题
• 依赖精简 — 默认依赖从 13 个减少到 4 个，降低供应链攻击面
• 纯 ESM 包 — 消除了 CJS/ESM 双包格式带来的潜在安全风险
• 安全头配置 — 支持自定义 HTTP 安全头和 CSP

export default defineConfig({
  security: {
    nonce: true,  // 自动生成 nonce（CSP 支持）
    integrity: true,  // 资源完整性校验
  },
  server: {
    headers: {
      'X-Content-Type-Options': 'nosniff',
      'X-Frame-Options': 'DENY',
    },
  },
})

技术对比

Rsbuild vs Vite

Rsbuild vs Webpack

Rsbuild vs Create React App

Rsbuild vs Vue-CLI

综合对比表

选型建议

• 新项目（React/Vue）：Rsbuild 或 Vite 均合适，Rsbuild 在 Webpack 迁移场景更有优势
• 已有 Webpack 大项目：Rsbuild（Rspack 兼容层降低迁移成本）
• 团队熟悉 Webpack 生态：Rsbuild 可直接复用 Webpack 知识
• 纯前端小型项目：Vite 和 Rsbuild 都可以
• 需要 React SSR：Next.js 仍更成熟，Rsbuild 可作为底层构建层
• Vue 项目：Vite 仍是官方推荐，Rsbuild 也是可行选择
• 组件库构建：考虑 Rslib（基于 Rsbuild）

最佳实践

生产配置优化

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'
 
export default defineConfig(({ env }) => {
  const isProd = env === 'production'
 
  return {
    plugins: [pluginReact()],
 
    output: {
      // 按经验拆分 chunk
      chunkSplit: {
        strategy: 'split-by-experience',
      },
      // 资源文件名带 hash（长期缓存）
      filename: {
        js: '[name].[contenthash:8].js',
        css: '[name].[contenthash:8].css',
      },
      // 生产环境关闭 Source Map（减小体积）
      sourceMap: {
        js: !isProd,
        css: !isProd,
      },
      // CDN 路径前缀
      assetPrefix: isProd ? 'https://cdn.example.com/' : '/',
      // 自动外部依赖（SSR 场景）
      autoExternal: true,
    },
 
    // 性能调优
    performance: {
      // 移除 console.log（生产环境）
      removeConsole: isProd,
      // 打印文件大小
      printFileSize: isProd,
      // 构建缓存
      buildCache: { enable: true },
    },
 
    // 安全配置
    security: {
      // 自动生成 nonce
      nonce: isProd,
      // 资源完整性校验
      integrity: isProd,
    },
  }
})

多框架迁移策略

从 Create-React-App 迁移：

# 1. 安装 Rsbuild
pnpm add -D @rsbuild/core @rsbuild/plugin-react
 
# 2. 创建 rsbuild.config.ts
cat > rsbuild.config.ts << 'EOF'
import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'
 
export default defineConfig({
  plugins: [pluginReact()],
  source: {
    entry: {
      index: './src/index.tsx',  // 与原 CRA 入口一致
    },
  },
})
EOF
 
# 3. 修改 package.json scripts
# "dev": "rsbuild dev",
# "build": "rsbuild build",
# "preview": "rsbuild preview"
 
# 4. 删除 react-scripts
pnpm remove react-scripts
 
# 5. 测试运行
pnpm dev

从 Webpack 迁移：

1. 安装 @rsbuild/core，创建 rsbuild.config.ts
2. 将 webpack.config.js 中的关键配置映射到 Rsbuild 配置
3. 使用 tools.rspack 保留不兼容的 Webpack 插件
4. 逐步移除 Webpack 特有的 loader，替换为 Rsbuild 内置支持
5. 运行 rsbuild inspect 检查最终配置是否正确

从 Vite 迁移：

1. 创建 Rsbuild 项目，对比 vite.config.ts 和 rsbuild.config.ts
2. 将 Vite 插件替换为 Rsbuild/Rspack 对应插件
3. 调整环境变量（Vite 使用 import.meta.env，Rsbuild 使用 process.env）
4. 处理 Vite 特有的 ?raw、?url 等导入语法

Monorepo 配置

// apps/web/rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'
import { pluginSourceBuild } from '@rsbuild/plugin-source-build'
 
export default defineConfig({
  plugins: [
    pluginReact(),
    pluginSourceBuild(),  // 自动识别 monorepo 中的本地包
  ],
  source: {
    entry: { index: './src/index.tsx' },
  },
  // 引用共享包
  tools: {
    rspack: {
      resolve: {
        alias: {
          '@shared/ui': '../../packages/ui/src',
          '@shared/utils': '../../packages/utils/src',
        },
      },
    },
  },
})

性能调优

export default defineConfig({
  performance: {
    // 构建缓存
    buildCache: { enable: true },
    // chunk 分割
    chunkSplit: {
      strategy: 'split-by-size',
      minSize: 20_000,
      maxSize: 500_000,
    },
  },
 
  // 按需分析产物
  output: {
    analyze: process.env.ANALYZE === 'true',
  },
 
  // 目标环境（影响 polyfill 和语法降级）
  output: {
    overrideBrowserslist: [
      'chrome >= 107',
      'edge >= 107',
      'firefox >= 104',
      'safari >= 16',
    ],
  },
})

技术局限与边界

Rspack 兼容性差异

Rsbuild 的局限主要来自底层 Rspack：

1. 部分 Webpack 插件不兼容 — 依赖 Webpack 内部 API 的插件可能无法在 Rspack 上运行：

   • 深度依赖 Webpack Compilation 内部结构的插件
   • 使用 compiler.hooks 中非公开 API 的插件
   • 依赖特定 Loader 交互的插件

   可以通过 tools.rspack 尝试使用，如果不行需要寻找替代方案或等待 Rspack 团队适配。

2. Loader 行为差异 — 虽然大部分 Webpack Loader 可以直接使用，但少数依赖 Webpack 特有机制的 Loader 可能存在行为差异：

   • thread-loader：Rspack 自带并行处理，不需要
   • cache-loader：Rspack 自带缓存，不需要
   • 部分自定义 Loader 使用了 Webpack 私有 API

3. 边缘配置差异 — Webpack 的一些冷门配置项在 Rspack 中可能不支持或行为不同。建议参考 Rspack 兼容性文档 了解具体差异。

生态成熟度

• 社区规模 — 相比 Webpack 和 Vite，Rsbuild / Rspack 的社区规模仍然较小，遇到问题时可参考的资料和解决方案相对有限
• 第三方资源 — 教程、博客、Stack Overflow 问答相对较少
• 插件数量 — 虽然兼容大部分 Webpack 插件，但专属的 Rsbuild 插件数量还在增长中
• 企业采用 — 字节内部大量使用，外部企业采用正在增长中

Node.js 版本要求

Rsbuild 2.0 将最低 Node.js 版本提升到 20.19+，这意味着：

• 不支持 Node.js 18 及以下版本
• 不支持 Node.js 19（非 LTS）
• 对于仍在使用旧版 Node.js 的项目，需要继续使用 Rsbuild 1.x 或升级 Node.js

纯 ESM 限制

Rsbuild 2.0 转为纯 ESM 包，移除了 CommonJS 产物。虽然 Node.js 20+ 支持 require(esm)，但对于需要在 CJS 环境中使用 Rsbuild JavaScript API 的场景，可能需要额外的适配工作。

其他限制

• 某些 Rust 原生依赖可能在特殊平台（如 Alpine musl）上需要额外配置
• SSR 场景下不如 Next.js/Nuxt 等全栈框架成熟
• 对于超大型 Monorepo（10000+ 模块），性能调优经验较少
• 学习成本：开发者需要了解 Rsbuild 的配置模型和插件系统，虽然与 Webpack 有相似之处，但仍有学习成本

学习成本

• 新工具链 — 需要理解 Rsbuild 的配置模型和插件系统
• Rspack 调试 — 当遇到 Rspack 层面的问题时，调试工具和经验相对 Webpack 较少。不过 Rsdoctor 工具正在弥补这一空白

学习资源

官方资源

• 官方文档（中文）：https://rsbuild.rs/zh/
• 官方文档（英文）：https://rsbuild.rs/
• v1 文档：https://v1.rsbuild.rs
• GitHub 仓库：https://github.com/web-infra-dev/rsbuild
• Rspack 文档：https://rspack.dev
• Rstack 工具链：https://rstack.dev
• 博客：https://rsbuild.rs/blog
  • Announcing Rsbuild 2.0
  • Announcing Rsbuild 2.1

迁移指南

• 从 Webpack 迁移
• 从 Create React App 迁移
• 从 Vue-CLI 迁移
• 从 Vite 迁移
• 从 v1 升级到 v2
• 从 Tsup 迁移到 Rslib

教程与指南

• 快速上手指南
• 配置参考
• 插件开发指南
• CLI 命令参考

社区

• GitHub Discussions：https://github.com/web-infra-dev/rsbuild/discussions
• awesome-rstack：https://github.com/web-infra-dev/awesome-rstack — 社区插件、模板和工具汇总
• npm 关键词：搜索 rsbuild-plugin 发现社区插件
• Best of JS：https://bestofjs.org/projects/rsbuild — 项目排名和趋势
• Discord 社区：官方文档中有加入社区的方式
• 字节跳动 Web Infra 团队技术博客

相关工具

• Rsdoctor — 构建分析与调试工具，帮助诊断构建性能和产物问题
• Rslib — 基于 Rsbuild 的库构建工具，适合开发 npm 包和组件库
• Rspress — 基于 Rsbuild 的文档站点生成器
• Modern.js — 字节全栈框架（底层可选 Rsbuild）

2026 年现状

最新版本

截至 2026 年 7 月，Rsbuild 的最新版本为 v2.1.4（2026 年 7 月 3 日发布）。主要的版本演进：

发展趋势

1. Rstack 工具链成熟 — Rsbuild 不再是一个孤立的构建工具，而是 Rstack 统一工具链的核心。Rslib、Rstest、Rspress、Rsdoctor 等工具形成了完整的开发生态。

2. 全栈框架支撑 — TanStack Start 选择 Rsbuild 作为构建工具，标志着 Rsbuild 从"构建工具"向"全栈框架基础设施"演进。

3. 性能持续领先 — 随着 Rspack 2.x 的持续优化，Rsbuild 的性能优势将进一步扩大。Rust 实现的 React Compiler（7-13x 加速）展示了 Rust 化带来的巨大潜力。

4. 社区快速增长 — npm 周下载量自 1.0 以来增长了 15 倍以上。越来越多的开源项目和商业项目选择 Rsbuild 作为构建工具。

5. 生态兼容性增强 — 通过兼容 Webpack 插件和 Loader，Rsbuild 降低了迁移门槛。同时，专属的 Rsbuild 插件生态也在快速成长。

6. AI 辅助迁移 — Rsbuild 团队推出了 rsbuild-v2-upgrade 编码代理技能，可以用 AI 辅助自动化迁移过程，这反映了工具链向 AI 友好方向发展的趋势。

7. Webpack 替代方案 — Rsbuild 被定位为 Webpack 的高性能替代方案，尤其在需要 Webpack 兼容但又追求性能的场景。随着 Webpack 进入维护模式，Rsbuild 的采用预计将继续增长。

社区活跃度

• GitHub Stars：3.3k+（持续增长）
• 维护团队：字节跳动 Web Infra 团队全职维护
• 发版频率：v2.0 到 v2.1 仅间隔约 2 个月，显示出极高的开发活跃度
• 下游项目：Modern.js、Storybook Rsbuild、Rspress、Rslib 等已完成 v2 升级
• 文档更新：中英文文档同步更新，质量较高

Rsbuild 已经成为 2026 年最值得关注的 Web 构建工具之一。它在性能、易用性和生态兼容性之间取得了优秀的平衡，特别适合追求构建速度、需要从 Webpack 迁移、或希望使用统一工具链的团队。Rsbuild 之于 Rspack，类似于 Create-React-App 之于 Webpack——但 Rsbuild 做得更好，因为它在零配置的同时保持了完整的可配置性和可扩展性。