close
  • 简体中文
      • 返回博客

      Rsbuild 2.0 发布

      2026 年 4 月 22 日

      Jiahan Chen
      Jiahan Chen
      @chenjiahan

      我们很高兴地宣布 Rsbuild 2.0 已经正式发布！

      Rsbuild 是一个由 Rspack 驱动的现代 Web 应用构建工具，也是 Rstack 生态的重要基础设施。围绕 Rsbuild，我们陆续打造了一系列上层工具，包括 Rspress、Rslib、Rstest、Storybook Rsbuild 等。这些工具通过 Rsbuild 共享统一的构建能力与插件体系，在应用开发、库构建、文档站点以及测试等场景中提供一致的开发体验。

      自 1.0 发布以来，Rsbuild 的 npm 周下载量已增长超过 15 倍，并成为 Rspack 新项目的首选构建工具。与此同时，越来越多团队从 webpack、Create React App 等工具迁移至 Rsbuild，并在构建效率和开发体验上获得了提升。

      为了帮助生态平稳升级到 2.0，我们投入了三个月进行验证与打磨，期间发布了 20 多个预览版本。目前，Rslib、Rstest、Rspress、Storybook Rsbuild 和 Modern.js 均已完成升级，并在生产环境中稳定运行。

      2.0 版本的主要改进包括：

      升级 Rspack 2.0

      Rsbuild 2.0 基于 Rspack 2.0 实现，因此也继承了 Rspack 2.0 在构建性能、产物优化和底层能力上的一系列改进。

      参考 Rspack 2.0 博客 了解这部分变更。

      React Server Components 支持

      React Server Components (RSC) 是一种预先渲染的 React 组件类型，它将数据获取与组件逻辑结合起来，并减少发送到客户端的 JavaScript。

      为了帮助基于 Rsbuild 的 Web 应用或框架更便捷地使用 RSC，我们提供了 rsbuild-plugin-rsc 插件。该插件基于 Rspack 内置的 RSC 能力实现，并借助 Rsbuild 的 Environments API 对 client 与 server 等多环境进行统一组织，降低了接入与配置成本。

      rsbuild.config.ts
      import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { pluginRSC } from 'rsbuild-plugin-rsc';

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginRSC({
      // Plugin options
    }),
  ],
  environments: {
    server: {
      // Server config...
    },
    client: {
      // Client config...
    },
  },
});

      目前该插件仍处于实验阶段。它已经能够运行 React Router 的 RSC 示例，也已经在 Modern.js 框架 中落地使用。

      另外，我们也在与 TanStack 团队展开合作，计划在后续版本中提供对 TanStack Start 和 TanStack 的 RSC 的支持。TanStack Start 是一个基于 TanStack Router 构建的全栈框架，我们非常期待结合双方的能力，共同探索 RSC 在不同场景下的更多可能性。

      开发服务器与客户端通信

      在支持 React Server Components 的过程中，我们发现一些场景需要在开发服务器与浏览器之间进行通信。例如，服务端完成某些操作后，需要主动通知客户端执行对应逻辑。

      为此，Rsbuild 2.0 提供了一组通信 API：

      • 服务端可通过 hot.send 向当前 environment 对应的客户端发送消息
      • 客户端可通过 import.meta.webpackHot.on 监听这些自定义事件

      这些 API 复用了现有的 HMR 通道，无需额外创建 WebSocket 连接。同时，消息仅会发送到匹配的 environment，避免不必要的广播。

      例如，当服务端状态发生变化时，通知客户端更新，而不是触发整页刷新：

      • 在服务端触发消息：
      rsbuild.config.ts
      server.environments.web.hot.send('data-change', {
  count: 1,
});
      • 在客户端监听消息：
      src/dev-sync.ts
      if (import.meta.webpackHot) {
  import.meta.webpackHot.on('data-change', ({ count }) => {
    console.log('data updated:', count);
  });
}

      扩展内置 Server

      Rsbuild 2.0 新增了 server.setup 选项，用于在开发服务器或预览服务器启动时执行初始化逻辑。

      该选项相较于原有的 server.setupMiddlewares 更为强大，用于对 Rsbuild 内置服务器进行定制，例如注册中间件、执行启动前任务，或根据 dev / preview 模式注入不同逻辑。通过 server.setup，这些能力可以直接在 Rsbuild 配置中完成。

      例如，为本地开发和预览环境添加一个简单的接口：

      rsbuild.config.ts
      export default {
  server: {
    setup: ({ server }) => {
      server.middlewares.use((req, res, next) => {
        if (req.url === '/api/health') {
          res.end('ok');
          return;
        }
        next();
      });
    },
  },
};

      支持自定义 logger

      通过新增的 customLogger 选项，你可以为多个 Rsbuild 实例自定义不同的 logger。

      这允许你为不同 Rsbuild 实例设置不同的日志级别、输出前缀，或者接入自定义的日志系统，而无需修改 全局 logger 实例。

      rsbuild.config.ts
      import { createLogger, defineConfig } from '@rsbuild/core';

const customLogger = createLogger({
  level: 'warn',
  prefix: '[web]',
});

export default defineConfig({
  customLogger,
});

      查看 日志指南 了解更多。

      更易用的拆包配置

      在 1.x 中，Rsbuild 通过 performance.chunkSplit 封装了常见的拆包策略，但它的设计与 Rspack 的 splitChunks 差异较大，开发者需要额外理解 strategy、forceSplitting 等概念。对于 coding agent 来说，也难以直接生成符合社区习惯的 splitChunks 配置，通常还需要进行额外转换。

      因此，Rsbuild 2.0 提供了新的 splitChunks 选项。它的行为与 Rspack 的 splitChunks 完全对齐，并通过额外的 preset 选项来提供预设配置。

      例如，使用 per-package 预设将每个 package 拆分成一个独立的 chunk：

      rsbuild.config.ts
      export default {
  splitChunks: {
    preset: 'per-package',
    chunks: 'all',
  },
};

      performance.chunkSplit 已在 2.0 中废弃，但现有配置仍可继续使用。建议参考 迁移 performance.chunkSplit 进行迁移。

      create-rsbuild 模板更新

      在核心能力升级的同时，我们也更新了 create-rsbuild 中的模板，使新项目的初始化流程更加贴近当前的开发实践：

      • 默认生成 AGENTS.md 文件，并支持在初始化时安装 rsbuild-best-practices 等 Agent Skills。
      • 创建 React 项目时，可以选择 React Compiler 作为可选工具。
      • 新增对 Rslint 的实验性支持，Rslint 是基于 typescript-go 的高性能代码检查工具。
      • 移除过时的 React 18 和 Vue 2 模板。

      精简依赖

      Rsbuild 2.0 对默认依赖进行了精简，将仅在特定场景下使用的包移出默认依赖，使默认依赖的数量从 13 个减少到 4 个，安装体积约减少 2 MB。

      本次调整主要涉及：

      默认 host 变化

      server.host 的默认值从 '0.0.0.0' 调整为 'localhost'。开发和预览服务器默认仅监听本机，不再对局域网内的其他设备开放。

      这一调整遵循「默认安全」的原则。在大多数本地开发场景中，开发服务器无需对外暴露。仅监听本机地址可以减少意外暴露，降低在共享网络环境中被扫描或攻击的风险。

      如果你需要在局域网设备上访问页面，可以显式开启网络访问：

      rsbuild.config.ts
      export default {
  server: {
    host: '0.0.0.0',
  },
};

      也可以通过 CLI 的 --host 参数快速开启：

      rsbuild --host

      Proxy 中间件升级

      开发服务器使用的 http-proxy-middleware 已经从 v2 升级至最新的 v4 版本，同时其底层依赖从已经停止维护的 http-proxy 切换为由 unjs 社区 积极维护的 httpxy。

      这主要带来几点改进：

      • 支持 HTTP/2 代理
      • 解决已知的安全问题
      • 不再依赖 Node.js 已废弃的 url.parse() API

      server.proxy 的部分字段已发生变更，升级时请参考 从 v1 升级到 v2。

      Pure ESM 包

      @rsbuild/core 现在以 pure ESM 包的形式发布，并移除了自身的 CommonJS 构建产物。这一调整仅影响 Rsbuild 本身的发布形式，使安装体积减少了约 500KB。

      在 Node.js 20 及以上版本中，运行时已原生支持通过 require(esm) 加载 ESM 模块。因此，对大多数仍通过 JavaScript API 使用 Rsbuild 的项目来说，这一变更通常不会带来实际影响，也无需额外修改现有代码。

      Node.js 支持

      从 2.0 开始，Rsbuild 最低支持的 Node.js 版本为 20.19+ 或 22.12+。由于 Node.js 18 已于 2025 年 4 月底结束维护，2.0 也不再继续支持该版本。

      我们通常会在某个 Node.js 版本进入 EOL 约一年后再移除支持，以为社区和用户预留更充足的升级时间。

      默认目标环境更新

      Rsbuild 2.0 调整了默认的目标环境，使产物面向更现代的浏览器和 Node.js 版本。

      对于 Web 产物，默认的 browserslist 现在对齐到 Baseline 的广泛可用范围。这里选取的是 2025-05-01 对应的目标集，表示截至该时间点已被主流浏览器广泛支持的 Web 平台能力。

      默认值变化如下：

      • Chrome 87 → 107
      • Edge 88 → 107
      • Firefox 78 → 104
      • Safari 14 → 16

      这意味着在未显式配置 browserslist 的情况下，Rsbuild 会默认输出更现代的 JavaScript 和 CSS，同时减少语法降级和 polyfill 的引入。

      对于 Node.js 产物，默认目标版本也从 Node.js 16 提升至 Node.js 20。

      如果你已经通过 .browserslistrc、package.json#browserslist 或 output.overrideBrowserslist 显式配置了目标环境，则不会受到上述调整的影响。

      ESM Node.js 产物

      在构建 Node.js 产物时，相比 Rsbuild v1 默认输出压缩后的 CommonJS 代码，Rsbuild 2.0 现在会默认输出未压缩的 ES modules 代码。

      这一调整更符合现代 Node 应用的主流实践。同时，服务端代码默认不压缩，有助于保留清晰的调试堆栈，提升问题排查效率。

      需要注意的是，运行时需要具备加载 ESM 的能力。例如在 package.json 中设置 "type": "module"，或者使用 .mjs 作为输出文件扩展名。如果你的项目仍依赖 CommonJS，可以显式切回原有行为：

      rsbuild.config.ts
      export default {
  output: {
    target: 'node',
    module: false,
    minify: true,
  },
};

      装饰器版本更新

      随着底层 SWC 支持 2023-11 装饰器版本，Rsbuild 将 decorators.version 默认值从 2022-03 调整为 2023-11。

      2023-11 是当前最新的提案版本，对应 2023 年 11 月 TC39 会议后的规范，同时也是 Babel 8 的默认行为。如果你需要保留旧行为，可以显式指定版本：

      rsbuild.config.ts
      export default {
  source: {
    decorators: {
      version: '2022-03',
    },
  },
};

      升级至 Rsbuild 2.0

      对于大多数项目来说，升级到 Rsbuild 2.0 是一个相对平滑的过程。尽管 2.0 引入了一些默认行为调整和不兼容变更，但大多数变更都提供了清晰的迁移路径，通常无需修改业务代码。

      如果你正在使用支持 skills 的 coding agent，可以安装 rsbuild-v2-upgrade skill，由 agent 自动协助完成依赖升级、配置调整和迁移检查，减少手动操作成本。

      npx skills add rstackjs/agent-skills --skill rsbuild-v2-upgrade

      完整的升级指南及所有不兼容变更，请参考 从 v1 升级到 v2。

      致谢

      Rsbuild 由 Rstack 团队主导开发，同时也离不开社区贡献者与所有用户的共同参与。自 1.0 发布以来，许多开发者通过贡献推动了 Rsbuild 的演进，在此感谢所有参与其中的朋友：

      @9aoy、@adammark、@ahabhgk、@alexUXUI、@bodia-uz、@Brennvo、@caohuilin、@Cheese-Yu、@chenjiahan、@Chevindu、@Colin3191、@colinaaa、 @CPunisher、@davide97g、@Deku-nattsu、@DeveshSapkale、@dovigod、@Draculabo、@easy1090、@escaton、@fansenze、@fi3ework、@gaoachao、@GiveMe-A-Name、 @GRAMMAC1、@hai-x、@hangCode2001、@hardfist、@hasnum-stack、@htoooth、@Huxpro、@ianzone、@iceprosurface、@inottn、@jerrykingxyz、@jkzing、 @JounQin、@JSerFeng、@JSH-data、@junhea、@junxiongchu、@lguzzon、@LingyuCoder、@lluisemper、@lxKylin、@mhutter、@miownag、@mycoin、 @nikhilsnayak、@notzheng、@Nsttt、@nyqykk、@puxiao、@qmakani、@quininer、@RobHannay、@roli-lpci、@s-chance、@s-r-x、@sagar-dwivedi、 @Sang-Sang33、@schu34、@ScriptedAlchemy、@Shucei、@shulaoda、@Simon-He95、@slobo、@snatvb、@SoonIter、@stormslowly、@SyMind、@T9-Forever、 @thinkasany、@Timeless0911、@TinsFox、@valorkin、@vegerot、@VenDream、@wangi4myself、@wChenonly、@wjw99830、@wralith、@wxiaoyun、@xbzhang2020、 @xc2、@xettri、@xiaohp、@xuexb、@xun082、@yifancong、@ymq001、@zackarychapple、@zalishchuk、@zoolsher