> 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 adapter 配置参考

安装与快速配置请查看 [Rslib 集成概览](/zh/integration/rslib.md)。本页包含完整的 adapter API、配置映射、cache 行为和调试方法。

## API

### `withRslibConfig(options)`

返回一个加载或接收 Rslib 配置并将其转换为 Rstest 配置的函数。

#### `cwd`

- **类型：** `string`
- **默认值：** `process.cwd()`

`cwd` 是用于解析 Rslib 配置文件的当前工作目录。

当你的 Rslib 配置文件位于不同目录，或者你在 monorepo 中运行测试（此时 `process.cwd()` 可能不是你的配置目录）时，可以指定 `cwd` 选项从不同的目录解析 Rslib 配置文件。

```ts
export default defineConfig({
  extends: withRslibConfig({
    cwd: './packages/my-lib',
  }),
});
```

#### `configPath`

- **类型：** `string`
- **默认值：** `'./rslib.config.ts'`

Rslib 配置文件的路径。

:::tip
如果同时提供 `config` 和 `configPath`，配置内容以 `config` 为准。
:::

#### `config`


[Added in v0.11.0](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.0)

- **类型：** `RslibConfig`
- **默认值：** `undefined`

要直接转换的内联 Rslib 配置对象。提供 `config` 后，适配器不会调用 Rslib 的 `loadConfig`。

如果同时提供了 `configPath`，适配器会将它作为配置文件元信息，用于 [`forceRerunTriggers`](/zh/config/test/force-rerun-triggers.md) 和 build cache 依赖解析，但配置内容仍以传入的 `config` 为准。

```ts
import { defineConfig as defineRslibConfig } from '@rslib/core';
import { defineConfig } from '@rstest/core';
import { withRslibConfig } from '@rstest/adapter-rslib';

const rslibConfig = defineRslibConfig({
  lib: [{ format: 'esm' }],
});

export default defineConfig({
  extends: withRslibConfig({
    config: rslibConfig,
  }),
});
```

#### `libId`

- **类型：** `string`
- **默认值：** `undefined`

要使用的 `lib` 字段中的 lib 配置 ID。设置为字符串以使用具有匹配 ID 的 lib 配置。

默认情况下，适配器使用 Rslib 的通用配置。如果你的 Rslib 配置有多个 lib 配置：

```ts
// rslib.config.ts
export default defineConfig({
  lib: [
    {
      id: 'core',
      format: 'esm',
      dts: true,
      source: {
        define: {
          IS_CORE: true,
        },
      },
    },
    {
      id: 'utils',
      format: 'esm',
      source: {
        define: {
          IS_CORE: false,
        },
      },
    },
  ],
  // 共享配置
});
```

你可以在 Rstest 配置中引用特定的 lib 配置。Rstest 会将 Rslib 的共享配置和具有匹配 `libId` 的 lib 配置调整为 Rstest 格式。

这里也不是直接复用整个 lib 配置。适配器只会提取该 lib 中与测试执行相关的 `source`、`output`、`tools`、`plugins` 和 `resolve` 配置，再与共享配置合并后转换为 Rstest 配置。

```ts
// 用于测试 'core' 环境
export default defineConfig({
  extends: withRslibConfig({
    libId: 'core',
  }),
  // core-specific test config
});
```

当你需要使用不同的配置独立测试应用程序的多个部分时，可以定义多个 Rstest project。每个 project 都可以通过设置 `libId` 选项来扩展特定的 lib 配置。

```ts
export default defineConfig({
  projects: [
    {
      extends: withRslibConfig({ libId: 'node' }),
      include: ['tests/node/**/*.{test,spec}.?(c|m)[jt]s'],
    },
    {
      extends: withRslibConfig({ libId: 'react' }),
      include: ['tests/react/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
    },
  ],
});
```

#### `modifyLibConfig`

- **类型：** `(config: RslibConfig) => RslibConfig | void`
- **默认值：** `undefined`

在 Rslib 配置转换为 Rstest 配置之前对其进行修改：

```ts
export default defineConfig({
  extends: withRslibConfig({
    modifyLibConfig: (libConfig) => {
      delete libConfig.source?.define;
      return libConfig;
    },
  }),
});
```

## Cache 行为

如果你在 Rslib 配置里开启了 `performance.buildCache`，`withRslibConfig()` 会把这项配置传给 Rstest，Rstest 仍会继续补充自己的缓存默认值，例如运行时摘要项和基于配置文件的失效条件。

如果你的 Rslib 配置没有开启 `performance.buildCache`，Rstest 默认也不会开启它。只有在你希望测试构建使用持久化缓存时，才需要在 Rstest 配置里显式设置 `performance.buildCache`：

```ts
import { defineConfig } from '@rstest/core';
import { withRslibConfig } from '@rstest/adapter-rslib';

export default defineConfig({
  extends: withRslibConfig(),
  performance: {
    buildCache: true,
  },
});
```

## 配置映射

适配器会自动将以下 Rslib 选项映射到 Rstest：

下表中列出的字段会被继承；没有列出的 Rslib 选项默认不会进入 Rstest 配置。这意味着 `dev`、`server`、`html` 等与测试运行无关的配置会被自动忽略。

| Rslib 选项                     | Rstest 等效项               | 说明                                         |
| ---------------------------- | ------------------------ | ------------------------------------------ |
| `root`                       | `root`                   | 项目根目录                                      |
| `lib.id` selected by `libId` | `name`                   | 被 `libId` 选中的 Lib 标识                       |
| `plugins`                    | `plugins`                | 插件配置                                       |
| `source.decorators`          | `source.decorators`      | 装饰器支持                                      |
| `source.assetsInclude`       | `source.assetsInclude`   | 额外的静态资源匹配规则                                |
| `source.define`              | `source.define`          | 全局常量                                       |
| `source.include`             | `source.include`         | 额外需要 SWC 编译的代码文件                           |
| `source.exclude`             | `source.exclude`         | 不需要 SWC 编译的代码文件                            |
| `source.transformImport`     | `source.transformImport` | 按需导入转换规则                                   |
| `source.tsconfigPath`        | `source.tsconfigPath`    | TypeScript 配置路径                            |
| `resolve`                    | `resolve`                | 模块解析                                       |
| `output.cssModules`          | `output.cssModules`      | CSS Modules 配置                             |
| `output.module`              | `output.module`          | 优先使用 `output.module`，否则回退到 `lib.format`    |
| `tools.rspack`               | `tools.rspack`           | Rspack 配置                                  |
| `tools.swc`                  | `tools.swc`              | SWC 配置                                     |
| `tools.bundlerChain`         | `tools.bundlerChain`     | Bundler chain 配置                           |
| `output.target`              | `testEnvironment`        | `web` 映射为 'happy-dom'，`node` 及其他映射为 'node' |

## 调试配置

如需查看适配器返回的解析后配置，可以打印结果：

```typescript
export default defineConfig({
  extends: async (user) => {
    const config = await withRslibConfig({ libId: 'react' })(user);
    console.log('Extended config:', JSON.stringify(config, null, 2));
    return config;
  },
});
```

## 相关文档

- [Rslib 配置概览](https://rslib.rs/config)
- [Rstest 配置概览](/zh/config/index.md)