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

# Rsbuild adapter 配置参考

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

## API

### `withRsbuildConfig(options)`

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

#### `cwd`

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

`cwd` 会传递给 Rsbuild 的 `loadConfig` 函数。它是用于解析 Rsbuild 配置文件的当前工作目录。

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

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

#### `configPath`

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

Rsbuild 配置文件的路径。

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

#### `config`


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

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

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

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

```ts
import { defineConfig as defineRsbuildConfig } from '@rsbuild/core';
import { defineConfig } from '@rstest/core';
import { withRsbuildConfig } from '@rstest/adapter-rsbuild';

const rsbuildConfig = defineRsbuildConfig({
  source: {
    define: {
      __DEV__: 'true',
    },
  },
});

export default defineConfig({
  extends: withRsbuildConfig({
    config: rsbuildConfig,
  }),
});
```

#### `environmentName`

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

要使用的 `environments` 字段中的环境名称，它将与通用配置合并。设置为一个字符串以使用具有匹配名称的环境配置。

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

```ts
// rsbuild.config.ts
export default {
  source: {
    define: {
      'process.env.NODE_ENV': '"development"',
    },
  },
  environments: {
    test: {
      source: {
        define: {
          'process.env.NODE_ENV': '"test"',
        },
      },
    },
    prod: {
      source: {
        define: {
          'process.env.NODE_ENV': '"production"',
        },
      },
    },
  },
};
```

你可以在 Rstest 配置中引用特定的环境配置。Rstest 将会把 Rsbuild 的共享配置和具有匹配 `environmentName` 的环境配置适配为 Rstest 格式。

```ts
// 用于测试 'test' 环境
export default defineConfig({
  extends: withRsbuildConfig({
    environmentName: 'test',
  }),
  // 测试环境特定的配置
});
```

当你需要使用不同的配置独立测试应用程序的多个部分时，你可以定义多个 Rstest 项目。每个项目可以通过设置 `environmentName` 选项来继承特定的环境配置。

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

#### `modifyRsbuildConfig`

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

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

```ts
export default defineConfig({
  extends: withRsbuildConfig({
    modifyRsbuildConfig: (rsbuildConfig) => {
      delete rsbuildConfig.source?.define;
      return rsbuildConfig;
    },
  }),
});
```

### `toRstestConfig(options)`

将已有的 Rsbuild 配置对象转换为 Rstest 配置，而不会加载配置文件。

```ts
import type { RsbuildConfig } from '@rsbuild/core';
import { defineConfig } from '@rstest/core';
import { toRstestConfig } from '@rstest/adapter-rsbuild';

const rsbuildConfig: RsbuildConfig = {
  resolve: {
    alias: {
      '@': './src',
    },
  },
};

export default defineConfig({
  extends: toRstestConfig({
    rsbuildConfig,
  }),
});
```

#### `rsbuildConfig`

- **类型：** `RsbuildConfig`

要转换的 Rsbuild 配置对象。

#### `configPath`

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

传入的 `rsbuildConfig` 对应的来源文件路径；它不会从该路径加载配置。适配器只用它将该文件加入 [`forceRerunTriggers`](/zh/config/test/force-rerun-triggers.md) 和 [performance.buildCache.buildDependencies](https://rsbuild.rs/zh/config/performance/build-cache#builddependencies)。

#### `environmentName`

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

要从 `environments` 字段中合并到通用配置的环境名称。

#### `modifyRsbuildConfig`

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

在将合并后的 Rsbuild 配置对象转换为 Rstest 配置之前对其进行修改。

## 配置映射

适配器会自动将这些 Rsbuild 选项映射到 Rstest：

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

| Rsbuild 选项               | Rstest 等效项               | 说明                                  |
| ------------------------ | ------------------------ | ----------------------------------- |
| `root`                   | `root`                   | 项目根目录                               |
| `name` from environment  | `name`                   | 环境标识符                               |
| `plugins`                | `plugins`                | 插件配置                                |
| `source.decorators`      | `source.decorators`      | 装饰器支持                               |
| `source.assetsInclude`   | `source.assetsInclude`   | 额外的静态资源匹配规则                         |
| `source.define`          | `source.define`          | 全局常量                                |
| `source.include`         | `source.include`         | 源文件包含模式                             |
| `source.exclude`         | `source.exclude`         | 源文件排除模式                             |
| `source.transformImport` | `source.transformImport` | 按需导入转换规则                            |
| `source.tsconfigPath`    | `source.tsconfigPath`    | TypeScript 配置文件路径                   |
| `resolve`                | `resolve`                | 模块解析                                |
| `output.cssModules`      | `output.cssModules`      | CSS 模块配置                            |
| `output.emitAssets`      | `output.emitAssets`      | 是否将导入的静态资源输出到磁盘                     |
| `output.module`          | `output.module`          | 输出模块类型                              |
| `performance.buildCache` | `performance.buildCache` | 复用并补充 rstest 场景默认值                  |
| `tools.rspack`           | `tools.rspack`           | Rspack 配置                           |
| `tools.swc`              | `tools.swc`              | SWC 配置                              |
| `tools.bundlerChain`     | `tools.bundlerChain`     | Bundler 链配置                         |
| `output.target`          | `testEnvironment`        | web 环境为 'happy-dom'，node 环境为 'node' |

另外，适配器还会移除 `rsbuild:type-check` 插件，因为类型检查不属于测试运行时所需的构建链路。

## 调试配置

要查看适配器返回的解析配置，可以将其包装并打印结果：

```typescript
export default defineConfig({
  extends: async (user) => {
    const config = await withRsbuildConfig()(user);
    console.log('继承的配置:', JSON.stringify(config, null, 2));
    return config;
  },
});
```

## 相关文档

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