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

import { PackageManagerTabs } from '@theme';

从 v1 升级到 v2

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

使用 Agent Skills

如果你在使用支持 Skills 的 Coding Agent，可以安装 rsbuild-v2-upgrade 技能来辅助完成 v1 到 v2 的升级流程。

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

安装后，让 Coding Agent 协助完成升级即可。

升级 Rsbuild 到 v2

将 @rsbuild/core 升级到 2.0 RC 版本。
如果你使用了 @rsbuild/plugin-react 或 @rsbuild/plugin-svgr，也需要同时将它们升级到 2.0 RC 版本，以保持与 @rsbuild/core 的版本兼容。例如：

{
  "devDependencies": {
    "@rsbuild/core": "^2.0.0-rc.0",
    "@rsbuild/plugin-react": "^2.0.0-rc.0",
    "@rsbuild/plugin-svgr": "^2.0.0-rc.0"
  }
}

其他 Rsbuild 插件也推荐升级到最新的版本：

# 升级当前目录中的 Rsbuild 依赖
npx taze major --include /rsbuild/ -w

# 或递归升级整个 monorepo 中的 Rsbuild 依赖
npx taze major --include /rsbuild/ -w -r

Rspack v2

Rsbuild v2 现在依赖 @rspack/core v2，如果你使用了自定义的 Rspack 配置或插件，可能需要进行相应的调整。

参考 Rspack v2 升级指南了解所有不兼容更新。

默认 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 polyfill 从 @rsbuild/core 的默认依赖变更为可选的 peer 依赖，这减少了 1.2MB 的安装体积。

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

Module Federation

如果你使用了 moduleFederation.options 选项，请在项目中手动安装 @module-federation/runtime-tools，它现在是 @rspack/core 的 optional peer 依赖：

这一变更仅影响通过 moduleFederation.options 使用 Module Federation v1.5 的项目。如果你使用的是 Module Federation v2，则不受影响。

配置

默认 host 变更

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

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

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

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

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

rsbuild --host

默认 decorators 版本

source.decorators.version 的默认值从 2022-03 变更为 2023-11。

对大多数项目来说，这一变化带来的实际影响很小。如果你的项目依赖此前的默认行为，可以显式指定 decorators 版本：

export default {
  source: {
    decorators: {
      version: '2022-03',
    },
  },
};

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.removeMomentLocale`

performance.removeMomentLocale 选项已被移除。

该选项原本用于从产物中移除 Moment.js 的语言包。但在 Rspack v2 中，Moment 的 locales 默认不会被打包，因此该选项已不再需要。

背景信息可参考 web-infra-dev/rsbuild#6991。

移除 `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],
};

迁移 `performance.chunkSplit`

performance.chunkSplit 已在 Rsbuild 2.0 中废弃，但暂未移除，仍可继续使用。

我们推荐使用新的 splitChunks 选项代替它，新选项对齐了 Rspack 的 optimization.splitChunks 配置，并提供了与 performance.chunkSplit.strategy 相似的预设选项。

strategy

strategy: 'split-by-experience' → splitChunks.preset: 'default'

export default {
-  performance: {
-    chunkSplit: {
-      strategy: 'split-by-experience',
-    },
-  },
+  splitChunks: {
+    preset: 'default',
+  },
};

strategy: 'split-by-module' → splitChunks.preset: 'per-package'

export default {
-  performance: {
-    chunkSplit: {
-      strategy: 'split-by-module',
-    },
-  },
+  splitChunks: {
+    preset: 'per-package',
+  },
};

strategy: 'single-vendor' → splitChunks.preset: 'single-vendor'

export default {
-  performance: {
-    chunkSplit: {
-      strategy: 'single-vendor',
-    },
-  },
+  splitChunks: {
+    preset: 'single-vendor',
+  },
};

strategy: 'all-in-one' → 关闭拆包

export default {
-  performance: {
-    chunkSplit: {
-      strategy: 'all-in-one',
-    },
-  },
+  splitChunks: false,
};

strategy: 'custom' + splitChunks → splitChunks.preset: 'none'

export default {
-  performance: {
-    chunkSplit: {
-      strategy: 'custom',
-      splitChunks: {
-        // ...
-      },
-    },
-  },
+  splitChunks: {
+    preset: 'none',
+    // ...
+  },
};

strategy: 'split-by-size' → 直接配置 minSize / maxSize

export default {
-  performance: {
-    chunkSplit: {
-      strategy: 'split-by-size',
-      minSize: 20000,
-      maxSize: 50000,
-    },
-  },
+  splitChunks: {
+    preset: 'none',
+    minSize: 20000,
+    maxSize: 50000,
+  },
};

override → 直接使用 splitChunks

export default {
-  performance: {
-    chunkSplit: {
-      override: {
-        // ...
-      },
-    },
-  },
+  splitChunks: {
+    // ...
+  },
};

forceSplitting

forceSplitting 是对 cacheGroups 的语法糖，可以直接替换为 cacheGroups：

export default {
-  performance: {
-    chunkSplit: {
-      forceSplitting: {
-        axios: /node_modules[\\/]axios/,
-      },
-    },
-  },
+  splitChunks: {
+    cacheGroups: {
+      axios: {
+        test: /node_modules[\\/]axios/,
+        name: 'axios',
+        chunks: 'all',
+        priority: 0, // 使用 single-vendor 时可设置为 1
+        enforce: true,
+      },
+    },
+  },
};

Proxy 中间件升级

Rsbuild 依赖的 http-proxy-middleware 从 v2 升级到了 v4，个别配置项发生了变化。

你可以根据以下示例进行迁移，或查看 http-proxy-middleware v3 不兼容更新了解更多细节。

context 选项替换为 pathFilter：

export default {
  server: {
    proxy: [
      {
-       context: '/api',
+       pathFilter: '/api',
        target: 'https://example.com',
      },
    ],
  },
};

事件改为使用 on 统一配置：

export default {
  server: {
    proxy: {
      '/api': {
-       onOpen: () => {},
-       onClose: () => {},
-       onError: () => {},
-       onProxyReq: () => {},
-       onProxyRes: () => {},
+       on: {
+         open: () => {},
+         close: () => {},
+         error: () => {},
+         proxyReq: () => {},
+         proxyRes: () => {},
+       },
      },
    },
  },
};

JavaScript API

移除 rsbuild.build() 中废弃的 compiler 参数
移除 rsbuild.startDevServer() 中废弃的 compiler 参数
移除 sockWrite 中废弃的 content-changed 消息类型。使用 full-reload 代替
重命名 rsbuild.onAfterStartProdServer 方法为 rsbuild.onAfterStartPreviewServer
重命名 rsbuild.onBeforeStartProdServer 方法为 rsbuild.onBeforeStartPreviewServer
loadConfig 方法的 loader 参数的默认值从 jiti 变更为 auto，优先使用原生 Node.js 加载器

插件 API

重命名 api.onAfterStartProdServer 钩子为 api.onAfterStartPreviewServer
重命名 api.onBeforeStartProdServer 钩子为 api.onBeforeStartPreviewServer

移除 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 相关的类型。

内置规则变化

Rsbuild 内置的 JS 和 CSS 转换规则现在使用了 oneOf 来区分不同的分支，如果你使用 tools.bundlerChain 或 api.modifyBundlerChain 修改了 JS 或 CSS 规则，可能需要进行相应调整。

JS 规则

内置 JS 规则现在拆分为两个 oneOf 分支：

CHAIN_ID.ONE_OF.JS_MAIN：用于 SWC 转换
CHAIN_ID.ONE_OF.JS_RAW：用于处理 ?raw 导入

如果你之前在 CHAIN_ID.RULE.JS 上添加 loader，需要迁移到 JS_MAIN 分支：

export default {
  tools: {
    bundlerChain(chain, { CHAIN_ID }) {
      const jsRule = chain.module.rule(CHAIN_ID.RULE.JS);

-     jsRule.use('my-loader').loader('my-loader');
+     jsRule
+       .oneOf(CHAIN_ID.ONE_OF.JS_MAIN)
+       .use('my-loader')
+       .loader('my-loader');
    },
  },
};

CSS 规则

内置 CSS 规则拆分为三个 oneOf 分支：

CHAIN_ID.ONE_OF.CSS_MAIN：常规 CSS 转换
CHAIN_ID.ONE_OF.CSS_RAW：用于处理 ?raw 导入
CHAIN_ID.ONE_OF.CSS_INLINE：用于处理 ?inline 导入

如果你之前在 CHAIN_ID.RULE.CSS 上添加 loader，需要迁移到 CSS_MAIN 分支：

export default {
  tools: {
    bundlerChain(chain, { CHAIN_ID }) {
      const cssRule = chain.module.rule(CHAIN_ID.RULE.CSS);

-     cssRule.use('my-css-loader').loader('my-css-loader');
+     cssRule
+       .oneOf(CHAIN_ID.ONE_OF.CSS_MAIN)
+       .use('my-css-loader')
+       .loader('my-css-loader');
    },
  },
};

Less / Sass / Stylus 插件的内置规则也已采用相同的 oneOf 结构，修改规则时请使用对应的 ONE_OF 分支。

其他

查询参数 ?__inline=false 已被移除，使用 ?url 代替。
dev.setupMiddlewares 配置项已废弃，请使用 server.setup 代替。
style-loader 从 v3 升级到了 v4，tools.styleLoader 的部分配置项发生变化，详见 style-loader v4.0.0 发布说明。
html.templateParameters 中废弃的默认参数已被移除：
- webpackConfig：使用 rspackConfig 代替。
- htmlWebpackPlugin：使用 htmlPlugin 代替。
如果你通过全局 logger.override() 自定义 Rsbuild 日志，升级到 v2 后需要改用 customLogger。因为 v2 的实例 logger 不再受全局 logger.override() 影响。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

从 v1 升级到 v2

使用 Agent Skills

升级 Rsbuild 到 v2

Rspack v2

默认 browserslist 更新

Web 产物

Node 产物

Node.js 支持

Pure ESM 包

依赖变更

Polyfill

Module Federation

配置

默认 host 变更

默认 decorators 版本

Node 产物

移除 `source.alias`

移除 `source.aliasStrategy`

移除 `performance.bundleAnalyze`

移除 `performance.removeMomentLocale`

移除 `performance.profile`

迁移 `performance.chunkSplit`

strategy

forceSplitting

Proxy 中间件升级

JavaScript API

插件 API

移除 webpack 支持

内置规则变化

JS 规则

CSS 规则

其他

Uh oh!

FilesExpand file tree

v1-to-v2.mdx

Latest commit

History

v1-to-v2.mdx

File metadata and controls

从 v1 升级到 v2

使用 Agent Skills

升级 Rsbuild 到 v2

Rspack v2

默认 browserslist 更新

Web 产物

Node 产物

Node.js 支持

Pure ESM 包

依赖变更

Polyfill

Module Federation

配置

默认 host 变更

默认 decorators 版本

Node 产物

移除 source.alias

移除 source.aliasStrategy

移除 performance.bundleAnalyze

移除 performance.removeMomentLocale

移除 performance.profile

迁移 performance.chunkSplit

strategy

forceSplitting

Proxy 中间件升级

JavaScript API

插件 API

移除 webpack 支持

内置规则变化

JS 规则

CSS 规则

其他

移除 `source.alias`

移除 `source.aliasStrategy`

移除 `performance.bundleAnalyze`

移除 `performance.removeMomentLocale`

移除 `performance.profile`

迁移 `performance.chunkSplit`