产物兼容性#

本节介绍如何指定支持的目标环境。

语法降级#

通过设置 lib.syntax，你可以选择 JavaScript 和 CSS 将被降级到的语法。你可以使用 Browserslist 的查询语法。Rslib 还支持常见的 ECMAScript 版本号，例如 ES2015。

Rslib 还支持使用 .browserslistrc 文件来设置。需要注意的是，lib.syntax 优先于 .browserslistrc。如果两者都存在，将使用 lib.syntax。

默认情况下，syntax 被设置为 ESNext，这代表将仅支持主流浏览器（Chrome / Firefox / Edge / macOS Safari / iOS Safari）或 Node.js 的最新版本，具体取决于 output.target。

Polyfill#

在处理兼容性问题之前，建议了解以下背景知识，以便更好地处理相关问题。请查看有关 语法降级和 API 降级 的背景知识。

浏览器#

通常，我们不需要为 npm 包注入 polyfill，这个步骤应该在 web 应用框架侧完成，但在某些场景下，我们需要注入 polyfill 以使我们的库直接在低版本浏览器中运行。

需要注意的是，这个插件不会转换你的代码语法，它只会为代码中使用的未支持函数注入 polyfill，将它们作为普通函数导入，而不是污染全局。你需要安装 core-js-pure 依赖。

设置#

polyfill 依赖于 Babel 注入 polyfill 代码，因此你需要安装 Rsbuild Babel 插件 和 babel-plugin-polyfill-corejs3 来注入 polyfill 代码。

npm add @rsbuild/plugin-babel babel-plugin-polyfill-corejs3 -D

并安装 core-js-pure 作为运行时依赖代码。

npm add core-js-pure

配置 Babel 插件，设置 targets 字段以指定目标浏览器版本。

1import { pluginBabel } from '@rsbuild/plugin-babel';
2import { defineConfig } from '@rslib/core';
3
4export default defineConfig({
5  lib: [
6    {
7      format: 'esm',
8    },
9  ],
10  plugins: [
11    pluginBabel({
12      babelLoaderOptions: {
13        plugins: [
14          [
15            require('babel-plugin-polyfill-corejs3'),
16            {
17              method: 'usage-pure',
18              targets: { ie: '10' },
19              version: '3.29',
20            },
21          ],
22        ],
23      },
24    }),
25  ],
26});

配置#

更多详细信息，请查看 babel-plugin-polyfill-corejs3 文档。

Node.js#

通过使用 @rsbuild/plugin-node-polyfill，Node 核心库的 polyfill 会自动注入到浏览器侧，允许你在浏览器侧使用这些模块。

设置#

Rslib 使用 @rsbuild/plugin-node-polyfill 提供 Node Polyfill 功能。

npm add @rsbuild/plugin-node-polyfill -D

然后将其添加到插件字段中。

import { defineConfig } from '@rslib/core';
import { pluginNodePolyfill } from '@rsbuild/plugin-node-polyfill';

export default defineConfig({
  lib: [{ format: 'esm' }],
  plugins: [pluginNodePolyfill()],
});

配置#

• 对于启用了 bundle 的项目，Node Polyfill 将被注入并包含在输出中。

• 对于未启用 bundle 的项目，默认情况下不会注入 polyfill。为了避免在每个模块中内联 polyfill，模块需要被 external，并手动添加到依赖中，请按照以下步骤操作：

  1. 配置 output.external 和 resolvedPolyfillToModules，你可以从 @rsbuild/plugin-node-polyfill 导入。这将 polyfill 模块 external 到已安装的 polyfill 依赖中。
  2. 安装使用的 polyfill 模块作为依赖。

  通过以下步骤，每个 polyfill 模块的使用将被替换为 externals 字段中的相应模块。更多详细信息，请查看

  Source
  的示例。

更多详细信息，请查看 @rsbuild/plugin-node-polyfill 文档，所有配置均适用于 Rslib。