简体中文

从 Rsbuild 0.x 迁移

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

查看 Breaking changes in Rsbuild v1.0.0 了解更多细节。

[重要] Lightning CSS loader

Rsbuild 现在默认启用 lightningcss-loader 来转换 CSS 文件，它取代了 autoprefixer 来添加 vendor prefixes，并提供了更好的性能。

@rsbuild/plugin-lightningcss 已被废弃且不再需要。
tools.autoprefixer 配置已被移除。

考虑到 Lightning CSS 有一些未覆盖的边缘情况，你仍然可以通过 postcss 配置文件启用 autoprefixer：

postcss.config.cjs

module.exports = {
  plugins: {
    autoprefixer: {},
  },
};

[重要] output.polyfill

Rsbuild v1 默认将 output.polyfill 设置为 'off'，这可以减少 polyfill 代码并默认生成更小的包。

如果你的应用需要 polyfill，请将 output.polyfill 设置为 'usage' 或 'entry'：

rsbuild.config.ts

export default {
  output: {
    polyfill: 'usage',
  },
};

[重要] source.decorators

Rsbuild 现在默认使用 2022-11 装饰器版本。这使得 Rsbuild 的默认行为与 TypeScript >= 5.0 和 esbuild >= 0.21.0 保持一致。

如果你在使用旧版装饰器，可以添加以下配置：

rsbuild.config.ts

import { defineConfig } from '@rsbuild/core';

export default defineConfig({
  source: {
    decorators: {
      version: 'legacy',
    },
  },
});

[重要] output.targets

TIP

Rsbuild v1 移除了 output.targets 选项，以及 source.alias / source.entry 等配置的 target 参数，改为通过 environments 配置以提供更灵活的多环境配置能力。

对比原有选项，environments 覆盖范围更广，可对更多配置项进行多环境差异化配置。详情可参考多环境构建。

移除 output.targets 配置，改用 output.target 和 environments 配置。

before:

export default {
  output: {
    targets: ['web', 'node'],
  },
};

after:

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
      },
    },
  },
};

[重要] Rspack 配置校验

Rsbuild 现在默认启用 Rspack 的 scheme 校验，以确保 Rspack 配置的正确性。

当 Rspack 配置的类型错误时，会抛出错误并终止构建。
当 Rspack 配置中存在多余的字段时，会抛出错误，但不会终止构建。

详见 Rspack - RSPACK_CONFIG_VALIDATE。

source.alias

移除 source.alias 函数的 target 参数，改用 environments 配置。

before:

export default {
  source: {
    alias: (alias, { target }) => {
      if (target === 'node') {
        alias['@common'] = './src/node/common';
      } else if (target === 'web') {
        alias['@common'] = './src/web/common';
      }
    },
  },
  output: {
    targets: ['web', 'node'],
  },
};

after:

export default {
  environments: {
    web: {
      source: {
        alias: {
          '@common': './src/web/common',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        alias: {
          '@common': './src/node/common',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};

source.entry

移除了 source.entry 函数用法，改为使用 environments 配置。

before:

export default {
  source: {
    entry({ target }) {
      if (target === 'web') {
        return {
          index: './src/index.client.js',
        };
      }
      if (target === 'node') {
        return {
          index: './src/index.server.js',
        };
      }
    },
  },
  output: {
    targets: ['web', 'node'],
  },
};

after:

export default {
  environments: {
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};

output.overrideBrowserslist

output.overrideBrowserslist 不再支持 Record<RsbuildTarget, string[]> 类型，使用 environments 配置代替。

before:

export default {
  output: {
    overrideBrowserslist: {
      web: ['iOS >= 9', 'Android >= 4.4'],
      node: ['node >= 20'],
    },
  },
};

after:

export default defineConfig({
  environments: {
    web: {
      output: {
        overrideBrowserslist: ['iOS >= 9', 'Android >= 4.4'],
      },
    },
    node: {
      output: {
        overrideBrowserslist: ['node >= 20'],
      },
    },
  },
});

output.emitAssets

output.emitAssets 调整为 boolean 类型，使用 environments 配置代替。

before:

export default {
  output: {
    targets: ['web', 'node'],
    emitAssets: ({ target }) => target !== 'node',
  },
};

after:

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        emitAssets: false,
      },
    },
  },
};

output.distPath.server

移除 output.distPath.server，使用 environments 配置代替。

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        distPath: {
          root: 'dist/server',
        },
      },
    },
  },
};

output.minify.html

Rsbuild v1 移除了 output.minify.html 和 output.minify.htmlOptions 选项，不再对 HTML 文件进行压缩。

之前 Rsbuild 使用 html-minifier-terser 来压缩 HTML 文件。但 html-minifier-terser 的性能无法满足 Rsbuild 应用的需求，并且在大多数情况下，压缩 HTML 带来的收益很小。

目前，Rsbuild 不再内置 html-minifier-terser，因此我们提供了一个独立的插件 rsbuild-plugin-html-minifier-terser 来支持 HTML 压缩。

rsbuild.config.ts

import { pluginHtmlMinifierTerser } from 'rsbuild-plugin-html-minifier-terser';

export default {
  plugins: [pluginHtmlMinifierTerser()],
};

我们计划在未来使用一些性能更好的基于 Rust 的 HTML 压缩器。

output.charset

output.charset 的默认值由 ascii 调整为 utf8。

如果你需要使用 ascii，可以添加配置：

export default {
  output: {
    charset: 'ascii',
  },
};

dev.startUrl

dev.startUrl 被重命名为 server.open：

export default {
  dev: {
    startUrl: true,
  },
  server: {
    open: true,
  },
};

dev.client.port

dev.client.port 的默认值从 <port> 调整为 '' (使用 location.port)。

你也可以使用之前的默认值：

export default {
  dev: {
    client: {
      port: '<port>',
    },
  },
};

html.appIcon

之前，html.appIcon 不支持 web app manifests，这意味着它仅适用于 iOS。

现在 html.appIcon 支持生成 web app manifests，并且 html.appIcon 的类型有变更。

before:

export default {
  html: {
    appIcon: './src/icon.png',
  },
};

after:

export default {
  html: {
    appIcon: {
      icons: [{ src: './src/icon.png', size: 180 }],
    },
  },
};

其他

Rsbuild 1.0 对插件、dev server 等 API 进行了部分调整和优化。

调整包括：

onBeforeBuild 钩子在 watch 模式下支持触发多次。
新增 onBeforeEnvironmentCompile 和 onAfterEnvironmentCompile 钩子，分别在执行单个 environment 的构建前/后触发。
移除 api.getHtmlPaths，改为 environment.htmlPaths。
移除 api.context.entry，改为 environment.entry。
移除 api.context.targets，改为 environment.target。
移除 rsbuildServer.onHTTPUpgrade，改为 rsbuildServer.connectWebSocket。

从 Rsbuild 0.x 迁移

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

查看 Breaking changes in Rsbuild v1.0.0 了解更多细节。

[重要] Lightning CSS loader

Rsbuild 现在默认启用 lightningcss-loader 来转换 CSS 文件，它取代了 autoprefixer 来添加 vendor prefixes，并提供了更好的性能。

@rsbuild/plugin-lightningcss 已被废弃且不再需要。
tools.autoprefixer 配置已被移除。

考虑到 Lightning CSS 有一些未覆盖的边缘情况，你仍然可以通过 postcss 配置文件启用 autoprefixer：

postcss.config.cjs

module.exports = {
  plugins: {
    autoprefixer: {},
  },
};

[重要] output.polyfill

Rsbuild v1 默认将 output.polyfill 设置为 'off'，这可以减少 polyfill 代码并默认生成更小的包。

如果你的应用需要 polyfill，请将 output.polyfill 设置为 'usage' 或 'entry'：

rsbuild.config.ts

export default {
  output: {
    polyfill: 'usage',
  },
};

[重要] source.decorators

Rsbuild 现在默认使用 2022-11 装饰器版本。这使得 Rsbuild 的默认行为与 TypeScript >= 5.0 和 esbuild >= 0.21.0 保持一致。

如果你在使用旧版装饰器，可以添加以下配置：

rsbuild.config.ts

import { defineConfig } from '@rsbuild/core';

export default defineConfig({
  source: {
    decorators: {
      version: 'legacy',
    },
  },
});

[重要] output.targets

TIP

Rsbuild v1 移除了 output.targets 选项，以及 source.alias / source.entry 等配置的 target 参数，改为通过 environments 配置以提供更灵活的多环境配置能力。

对比原有选项，environments 覆盖范围更广，可对更多配置项进行多环境差异化配置。详情可参考多环境构建。

移除 output.targets 配置，改用 output.target 和 environments 配置。

before:

export default {
  output: {
    targets: ['web', 'node'],
  },
};

after:

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
      },
    },
  },
};

[重要] Rspack 配置校验

Rsbuild 现在默认启用 Rspack 的 scheme 校验，以确保 Rspack 配置的正确性。

当 Rspack 配置的类型错误时，会抛出错误并终止构建。
当 Rspack 配置中存在多余的字段时，会抛出错误，但不会终止构建。

详见 Rspack - RSPACK_CONFIG_VALIDATE。

source.alias

移除 source.alias 函数的 target 参数，改用 environments 配置。

before:

export default {
  source: {
    alias: (alias, { target }) => {
      if (target === 'node') {
        alias['@common'] = './src/node/common';
      } else if (target === 'web') {
        alias['@common'] = './src/web/common';
      }
    },
  },
  output: {
    targets: ['web', 'node'],
  },
};

after:

export default {
  environments: {
    web: {
      source: {
        alias: {
          '@common': './src/web/common',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        alias: {
          '@common': './src/node/common',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};

source.entry

移除了 source.entry 函数用法，改为使用 environments 配置。

before:

export default {
  source: {
    entry({ target }) {
      if (target === 'web') {
        return {
          index: './src/index.client.js',
        };
      }
      if (target === 'node') {
        return {
          index: './src/index.server.js',
        };
      }
    },
  },
  output: {
    targets: ['web', 'node'],
  },
};

after:

export default {
  environments: {
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};

output.overrideBrowserslist

output.overrideBrowserslist 不再支持 Record<RsbuildTarget, string[]> 类型，使用 environments 配置代替。

before:

export default {
  output: {
    overrideBrowserslist: {
      web: ['iOS >= 9', 'Android >= 4.4'],
      node: ['node >= 20'],
    },
  },
};

after:

export default defineConfig({
  environments: {
    web: {
      output: {
        overrideBrowserslist: ['iOS >= 9', 'Android >= 4.4'],
      },
    },
    node: {
      output: {
        overrideBrowserslist: ['node >= 20'],
      },
    },
  },
});

output.emitAssets

output.emitAssets 调整为 boolean 类型，使用 environments 配置代替。

before:

export default {
  output: {
    targets: ['web', 'node'],
    emitAssets: ({ target }) => target !== 'node',
  },
};

after:

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        emitAssets: false,
      },
    },
  },
};

output.distPath.server

移除 output.distPath.server，使用 environments 配置代替。

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        distPath: {
          root: 'dist/server',
        },
      },
    },
  },
};

output.minify.html

Rsbuild v1 移除了 output.minify.html 和 output.minify.htmlOptions 选项，不再对 HTML 文件进行压缩。

目前，Rsbuild 不再内置 html-minifier-terser，因此我们提供了一个独立的插件 rsbuild-plugin-html-minifier-terser 来支持 HTML 压缩。

rsbuild.config.ts

import { pluginHtmlMinifierTerser } from 'rsbuild-plugin-html-minifier-terser';

export default {
  plugins: [pluginHtmlMinifierTerser()],
};

我们计划在未来使用一些性能更好的基于 Rust 的 HTML 压缩器。

output.charset

output.charset 的默认值由 ascii 调整为 utf8。

如果你需要使用 ascii，可以添加配置：

export default {
  output: {
    charset: 'ascii',
  },
};

dev.startUrl

dev.startUrl 被重命名为 server.open：

export default {
  dev: {
    startUrl: true,
  },
  server: {
    open: true,
  },
};

dev.client.port

dev.client.port 的默认值从 <port> 调整为 '' (使用 location.port)。

你也可以使用之前的默认值：

export default {
  dev: {
    client: {
      port: '<port>',
    },
  },
};

html.appIcon

之前，html.appIcon 不支持 web app manifests，这意味着它仅适用于 iOS。

现在 html.appIcon 支持生成 web app manifests，并且 html.appIcon 的类型有变更。

before:

export default {
  html: {
    appIcon: './src/icon.png',
  },
};

after:

export default {
  html: {
    appIcon: {
      icons: [{ src: './src/icon.png', size: 180 }],
    },
  },
};

其他

Rsbuild 1.0 对插件、dev server 等 API 进行了部分调整和优化。

调整包括：

onBeforeBuild 钩子在 watch 模式下支持触发多次。
新增 onBeforeEnvironmentCompile 和 onAfterEnvironmentCompile 钩子，分别在执行单个 environment 的构建前/后触发。
移除 api.getHtmlPaths，改为 environment.htmlPaths。
移除 api.context.entry，改为 environment.entry。
移除 api.context.targets，改为 environment.target。
移除 rsbuildServer.onHTTPUpgrade，改为 rsbuildServer.connectWebSocket。

#从 Rsbuild 0.x 迁移

#[重要] Lightning CSS loader

#[重要] output.polyfill

#[重要] source.decorators

#[重要] output.targets

#[重要] Rspack 配置校验

#source.alias

#source.entry

#output.overrideBrowserslist

#output.emitAssets

#output.distPath.server

#output.minify.html

#output.charset

#dev.startUrl

#dev.client.port

#html.appIcon

#其他

#从 Rsbuild 0.x 迁移

#[重要] Lightning CSS loader

#[重要] output.polyfill

#[重要] source.decorators

#[重要] output.targets

#[重要] Rspack 配置校验

#source.alias

#source.entry

#output.overrideBrowserslist

#output.emitAssets

#output.distPath.server

#output.minify.html

#output.charset

#dev.startUrl

#dev.client.port

#html.appIcon

#其他

从 Rsbuild 0.x 迁移

[重要] Lightning CSS loader

[重要] output.polyfill

[重要] source.decorators

[重要] output.targets

[重要] Rspack 配置校验

source.alias

source.entry

output.overrideBrowserslist

output.emitAssets

output.distPath.server

output.minify.html

output.charset

dev.startUrl

dev.client.port

html.appIcon

其他

从 Rsbuild 0.x 迁移

[重要] Lightning CSS loader

[重要] output.polyfill

[重要] source.decorators

[重要] output.targets

[重要] Rspack 配置校验

source.alias

source.entry

output.overrideBrowserslist

output.emitAssets

output.distPath.server

output.minify.html

output.charset

dev.startUrl

dev.client.port

html.appIcon

其他