#从 v1 升级到 v2

当前文档列出了从 Rsbuild 1.x 到 2.0 的所有不兼容更新，你可以参考此文档来迁移。

本指南仍在持续完善中。随着 Rsbuild 2.0 Beta 的推进，相关内容将逐步补充。

#默认 browserslist 更新

在 Rsbuild 2.0 中，默认的 browserslist 已进行更新，以更好地反映现代 Web 平台的基线水平。

#Web 产物

默认的 Web browserslist 已升级到更现代的 Baseline。新的默认值对应于 baseline widely available on 2025-05-01：

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

这一变化会影响 JavaScript 和 CSS 的转换结果，以及 polyfill 的注入方式。

如果你的项目已经定义了自己的 browserslist 配置，例如通过 .browserslistrc 或 package.json#browserslist，Rsbuild 将继续使用该配置。默认值只会在未检测到任何 browserslist 配置时生效。

如果你希望保持之前的行为，可以在项目根目录创建一个 .browserslistrc 文件：

chrome >= 87
edge >= 88
firefox >= 78
safari >= 14

#Node 产物

Rsbuild 2.0 也更新了默认的 Node.js 产物版本。由于 Node.js 18 已于 2025 年 4 月 结束维护，Rsbuild 现在默认使用 Node 20+。

• Node 16 → 20

如果你希望保持之前的行为，可以通过 output.overrideBrowserslist 进行配置：

export default {
  output: {
    target: 'node',
    overrideBrowserslist: ['node >= 16'],
  },
};

#Node.js 支持

Rsbuild 2.0 最低支持的 Node.js 版本为 20.19+ 或 22.12+，不再支持 Node.js 18。

#Pure ESM 包

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

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

这一变更不影响 Rsbuild 构建 CommonJS 产物的能力，相关的构建行为和配置方式也保持不变。

#Polyfill 依赖变更

core-js 从 @rsbuild/core 的默认依赖变更为可选的 peer 依赖，这减少了 1.2MB 的安装体积。

如果你启用了 output.polyfill，请在项目中安装 core-js v3：

npm add core-js

yarn add core-js

pnpm add core-js

bun add core-js

deno add npm:core-js

#配置

#默认 host 变更

server.host 的默认值从 '0.0.0.0' 变更为 'localhost'。

这防止了开发服务器默认暴露在局域网中，从而确保了"默认安全"。

如果你需要从同一局域网内的其他设备访问服务器（例如进行移动端测试），可以将 host 手动设置为 '0.0.0.0'：

export default {
  server: {
    host: '0.0.0.0',
  },
};

你也可以使用 CLI 的 --host 选项来开启网络访问：

rsbuild dev --host

#Node 产物

当 output.target 为 node 时，Rsbuild 2.0 会通过 output.module 默认输出 ESM 产物，并保持 output.minify 关闭。在 Rsbuild 1.x 中，默认行为是输出 CommonJS 且开启压缩。

该调整更贴近 Node 的现代 ESM 生态，同时保留更清晰的调试堆栈与排查体验。

因此运行时需要支持加载 ESM（例如在 package.json 中设置 "type": "module" 或输出 .mjs 文件），否则需要显式切回 CommonJS。

如果你希望恢复 v1 的行为，可以显式禁用 ESM 并开启压缩：

export default {
  output: {
    target: 'node',
    module: false,
    minify: true,
  },
};

#移除 source.alias

废弃的 source.alias 选项已被移除，使用 resolve.alias 进行替代。

export default {
- source: {
+ resolve: {
    alias: {
      '@': './src',
    },
  },
};

#移除 source.aliasStrategy

废弃的 source.aliasStrategy 选项已被移除，使用 resolve.aliasStrategy 进行替代。

export default {
- source: {
+ resolve: {
    aliasStrategy: 'prefer-alias',
  },
};

#移除 performance.bundleAnalyze

废弃的 performance.bundleAnalyze 选项已被移除。

早期 Rsbuild 内置了 webpack-bundle-analyzer，但如今 Rsdoctor 已支持产物体积分析，因此无需在 @rsbuild/core 中继续内置；同时移除内置依赖可以降低安装体积。

推荐使用 Rsdoctor 分析产物体积，或通过 tools.rspack 自行注册 webpack-bundle-analyzer：

import { BundleAnalyzerPlugin } from 'webpack-bundle-analyzer';

export default {
  tools: {
    rspack: {
      plugins: [
        new BundleAnalyzerPlugin({
          analyzerMode: 'static',
        }),
      ],
    },
  },
};

#移除 performance.profile

performance.profile 选项已被移除。如果你依赖它来输出 stats JSON 文件，可以在自定义插件中调用 stats.toJson() 代替：

import { writeFileSync } from 'node:fs';
import { join } from 'node:path';

const statsJsonPlugin = {
  name: 'stats-json-plugin',
  setup(api) {
    api.onAfterBuild(({ stats }) => {
      writeFileSync(
        join(api.context.distPath, 'stats.json'),
        JSON.stringify(stats?.toJson({}), null, 2),
      );
    });
  },
};

export default {
  plugins: [statsJsonPlugin],
};

#移除 HTML 模板参数

html.templateParameters 中废弃的默认参数已被移除：

• webpackConfig：使用 rspackConfig 代替。
• htmlWebpackPlugin：使用 htmlPlugin 代替。

#JavaScript API

• 移除 rsbuild.build() 中废弃的 compiler 参数
• 移除 rsbuild.startDevServer() 中废弃的 compiler 参数
• 移除 sockWrite 中废弃的 content-changed 消息类型，使用 static-changed 代替

#移除 webpack 支持

Rsbuild 2.0 不再支持使用 webpack 作为打包工具。在 Rsbuild 1.x 版本中，该能力主要用于验证 Rspack 与 webpack 之间的兼容性。随着 Rspack 的逐步成熟和稳定，这一用途已不再必要，因此相关支持被正式移除。

具体变更如下：

• 移除 @rsbuild/webpack 包。
• 移除 @rsbuild/plugin-webpack-swc 包。
• 移除 provider 配置项。
• 移除 tools.webpack 和 tools.webpackChain 配置项。
• 移除 api.modifyWebpackChain 和 api.modifyWebpackConfig 插件钩子。
• 移除 api.context.bundlerType 中的 webpack 类型。
• 移除 webpack 相关的类型。