> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 配置 Rslib

通过 Rslib 配置，你可以定义库的产物形式，并控制每份产物的构建行为。

## 配置结构

Rslib 配置由两类配置组成：

- [lib 配置](/zh/config/lib.md)：描述库产物本身，包括输出格式、产物结构和语法目标等。
- [Rsbuild 配置](/zh/config/rsbuild.md)：控制底层编译和构建行为，包括模块解析、源码处理与相关插件等。

`lib` 是一个可选的对象数组，每个对象对应一份产物，可包含上述两类配置。写在 `lib` 项中的配置仅作用于对应产物；写在 `lib` 字段外的配置则作为顶层配置，在各个 `lib` 产物之间共享。

Rslib 会按照 [配置合并规则](https://rsbuild.rs/zh/api/javascript-api/core#合并规则) 将顶层配置与每个 `lib` 项合并。

### lib 配置

lib 配置可以写在 `lib` 项中，用于单独配置对应产物。[部分 lib 配置](/zh/config/lib.md#顶层-lib-配置)也可以写在 `lib` 字段外作为顶层配置，在各个 `lib` 产物之间共享。

例如，将 CJS 产物的 [`syntax`](/zh/config/lib/syntax.md) 设置为 `es2020`，并通过顶层配置将其余产物的 `syntax` 设置为 `es2021`：

```js title="rslib.config.mjs"
export default {
  lib: [
    {
      format: 'esm',
    },
    {
      format: 'cjs',
      syntax: 'es2020',
    },
  ],
  syntax: 'es2021',
};
```

合并后，ESM 产物的 `syntax` 为 `es2021`，CJS 产物的 `syntax` 为 `es2020`。

当你只需要基于默认配置生成一份 ESM 产物时，可以省略 `lib` 字段，这等价于配置 `lib: [{}]`。

### Rsbuild 配置

Rsbuild 配置可以写在 `lib` 字段外作为顶层配置，在各个 `lib` 产物之间共享；也可以写在 `lib` 项中，用于单独配置对应产物。

例如，将 ESM 产物的 [output.target](/zh/config/rsbuild/output.md#outputtarget) 设置为 `'web'`，并通过顶层配置将其余产物的 `output.target` 设置为 `'node'`：

```js title="rslib.config.mjs"
export default {
  lib: [
    {
      format: 'esm',
      output: {
        target: 'web',
      },
    },
    {
      format: 'cjs',
    },
  ],
  output: {
    target: 'node',
  },
};
```

合并后，ESM 产物的 `output.target` 为 `'web'`，CJS 产物的 `output.target` 为 `'node'`。

:::info

- Rslib 会在内部生成 Rsbuild 的 [environments](https://rsbuild.rs/zh/config/environments) 配置，你可以开启[调试模式](#调试模式)，或运行 [rslib inspect](/zh/guide/basic/cli.md#rslib-inspect) 命令来查看最终生成的配置。

- 你可以在[配置总览](/zh/config/index.md)页面找到所有配置项的详细说明。

:::

## 配置文件

当你使用 Rslib 的 CLI 命令时，Rslib 会自动读取当前项目根目录下的配置文件，按照以下顺序进行解析：

- `rslib.config.mjs`
- `rslib.config.ts`
- `rslib.config.js`
- `rslib.config.cjs`
- `rslib.config.mts`
- `rslib.config.cts`

我们推荐使用 `.mjs` 或 `.ts` 格式的配置文件，并从 `@rslib/core` 中导入 `defineConfig` 工具函数, 它提供了友好的 TypeScript 类型推导和自动补全，可以帮助你避免配置中的错误。

比如在 `rslib.config.ts` 中，你可以定义 Rslib 的 [syntax](/zh/config/lib/syntax.md) 配置和 Rsbuild 的 [output.target](https://rsbuild.rs/zh/config/output/target#outputtarget) 配置：

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      syntax: 'es2021',
    },
  ],
  output: {
    target: 'node',
  },
});
```

如果你在开发一个非 TypeScript 项目，可以使用 `.mjs` 格式的配置文件。

:::tip

当你使用 `.ts`, `.mts` 和 `.cts` 后缀时，Rslib 会使用 [jiti](https://github.com/unjs/jiti) 来加载配置文件，提供 ESM 与 CommonJS 的互操作性，模块解析的行为与 Node.js 原生行为存在一定差异。

:::

## 指定配置文件

Rslib CLI 通过 `--config` 选项来指定配置文件，可以设置为相对路径或绝对路径。

例如，你需要在执行 `build` 命令时使用 `rslib.prod.config.mjs` 文件，可以在 `package.json` 中添加如下配置：

```json title="package.json"
{
  "scripts": {
    "build": "rslib --config rslib.prod.config.mjs"
  }
}
```

你也可以将 `--config` 选项缩写为 `-c`：

```bash
rslib -c rslib.prod.config.mjs
```

## 指定加载方式

Rslib 提供了三种配置文件加载方式：

- `jiti`：当你使用 `.ts`, `.mts` 和 `.cts` 后缀的配置文件时，Rslib 会使用 [jiti](https://github.com/unjs/jiti) 来加载配置文件，提供 ESM 与 CommonJS 的互操作性，模块解析的行为与 Node.js 原生行为存在一定差异。

- `native`：使用 Node.js 原生 loader 来加载配置文件，这可以保证模块解析的行为与 Node.js 原生行为一致，并且性能更好。这要求你使用的 JavaScript 运行时已经原生支持 TypeScript。

  例如，Node.js 从 v22.6.0 开始已经原生支持 TypeScript，你可以运行如下命令来使用 Node.js 原生 loader 来加载配置文件：

  ```bash
  # Node.js >= v22.18.0
  # 不需要设置 --experimental-strip-types
  npx rslib --config-loader native

  # Node.js v22.6.0 - v22.17.1
  # 需要设置 --experimental-strip-types
  NODE_OPTIONS="--experimental-strip-types" npx rslib --config-loader native
  ```

- `auto`（默认）：优先使用 Node.js 原生 loader 来加载配置文件，失败时回退到使用 jiti 加载。

### 关于 Node.js 原生 loader

使用 Node.js 原生 loader 时，请注意以下限制：

1. 导入 JSON 文件时，需要使用 import attributes：

   ```ts
   import pkgJson from './package.json' with { type: 'json' }; // ✅ 正确
   import pkgJson from './package.json'; // ❌ 错误
   ```

2. 导入 TypeScript 文件时，需要包含 `.ts` 扩展名：

   ```ts
   import baseConfig from './rslib.base.config.ts'; // ✅ 正确
   import baseConfig from './rslib.base.config'; // ❌ 错误
   ```

> 详见 [Node.js - Running TypeScript Natively](https://nodejs.org/en/learn/typescript/run-natively#running-typescript-natively)。

## 使用环境变量

在配置文件中，你可以使用 Node.js 环境变量，来动态写入不同的配置：

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
    },
  ],
  source: {
    alias: {
      '@language':
        process.env.LANGUAGE === 'en'
          ? './src/language/en.js'
          : './src/language/zh.js',
    },
  },
});
```

## 配置 Rsbuild

Rslib 允许你使用绝大部分的 Rsbuild 配置。目前不支持使用 `environments` 配置，因为该字段会在 Rslib 内部生成。

- 参考 [Rsbuild 配置](/zh/config/rsbuild/index.md) 了解常用的 Rsbuild 配置。
- 参考 [Rsbuild 文档](https://rsbuild.rs/zh/config/) 了解所有 Rsbuild 配置。

## 配置 Rspack

Rslib 基于 Rsbuild 构建，Rsbuild 支持直接修改 Rspack 配置对象，也支持通过 `rspack-chain` 修改 Rsbuild 内置的 Rspack 配置。这意味着你可以在 Rslib 项目中配置 Rspack 相关配置。

详情请参考 [配置 Rspack](https://rsbuild.rs/zh/guide/configuration/rspack)。

## 调试模式

你可以在执行构建时添加 `DEBUG=rslib` 环境变量来开启 Rslib 的调试模式。

```bash
DEBUG=rslib pnpm build
```

在调试模式下，Rslib 会输出一些额外的日志信息，并将内部经过 Rslib 处理最终生成的 Rsbuild 配置和 Rspack 配置写入到产物目录下，便于开发者查看和调试。

以下是一个例子，这个库设置了 CJS 和 ESM 两种输出格式：

```
Inspect config succeed, open following files to view the content:

  - Rsbuild Config (esm): /project/dist/.rsbuild/rsbuild.config.esm.mjs
  - Rsbuild Config (cjs): /project/dist/.rsbuild/rsbuild.config.cjs.mjs
  - Rspack Config (esm): /project/dist/.rsbuild/rspack.config.esm.mjs
  - Rspack Config (cjs): /project/dist/.rsbuild/rspack.config.cjs.mjs
  - Rslib Config: /project/dist/.rsbuild/rslib.config.mjs
```

- 打开生成的 `/dist/.rsbuild/rsbuild.config.esm.mjs` 文件，即可查看 Rsbuild 配置的完整内容。
- 打开生成的 `/dist/.rsbuild/rspack.config.esm.mjs` 文件，即可查看 Rspack 配置的完整内容。
- 打开生成的 `/dist/.rsbuild/rslib.config.mjs` 文件，即可查看 Rslib 配置的完整内容。