#Rspack adapter 配置参考

安装、快速配置和重要注意事项请查看 Rspack 集成概览。本页包含完整的 adapter API、兼容性映射和调试方法。

#API

#withRspackConfig(options)

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

#cwd

• 类型： string
• 默认值： process.cwd()

用于解析 Rspack 配置文件的工作目录。

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

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

#configPath

• 类型： string
• 默认值： './rspack.config.ts'

Rspack 配置文件的路径。

#configName

• 类型： string
• 默认值： undefined

当 Rspack 配置文件使用多配置时，选择指定名称的配置。设置为字符串以使用具有匹配 name 字段的配置。

如果你的 Rspack 配置导出了一个配置数组：

// rspack.config.ts
export default [
  {
    name: 'client',
    target: 'web',
    entry: './src/client.ts',
    // ...
  },
  {
    name: 'server',
    target: 'node',
    entry: './src/server.ts',
    // ...
  },
];

你可以在 Rstest 配置中选择特定的配置：

export default defineConfig({
  extends: withRspackConfig({
    configName: 'client',
  }),
});

当你需要使用不同的配置独立测试应用程序的多个部分时，你可以定义多个 Rstest 项目：

export default defineConfig({
  projects: [
    {
      extends: withRspackConfig({ configName: 'server' }),
      include: ['tests/server/**/*.{test,spec}.?(c|m)[jt]s'],
    },
    {
      extends: withRspackConfig({ configName: 'client' }),
      include: ['tests/client/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
    },
  ],
});

#env

• 类型： Record<string, unknown> | string[]
• 默认值： undefined

传递给 Rspack 配置函数的环境变量。当 rspack.config.ts 导出一个函数时，对应其 env 参数：

// rspack.config.ts
export default (env) => {
  console.log(env); // 接收来自适配器的值
  return {/* ... */};
};

#nodeEnv

• 类型： string
• 默认值： undefined

加载 Rspack 配置时使用的 NODE_ENV 值。

#modifyRspackConfig

• 类型： (config: RspackOptions) => RspackOptions
• 默认值： undefined

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

export default defineConfig({
  extends: withRspackConfig({
    modifyRspackConfig: (rspackConfig) => {
      delete rspackConfig.resolve?.alias;
      return rspackConfig;
    },
  }),
});

#配置映射

withRspackConfig 不会将整份 Rspack 配置原样复制到 test compiler。它会根据行为所属的层级处理每个选项：有直接对应关系的概念会转换为 Rstest 配置，兼容的 compiler 选项会传给 Rspack，而与生成的 test build 冲突的设置仍由 Rstest 控制。

以下表格覆盖 Rspack 2.1 的全部 top-level 选项。部分选项会出现在不止一个表格中，因为其不同子项由不同层负责。例如，Rstest 需要理解 resolve.alias，而 resolve.fallback 必须交给 Rspack；类似地，Rstest 会根据 cache 派生自己的缓存，但不会复用其中每一个 persistent cache 调优选项。

部分 Rspack 选项在 Rstest 中有直接对应项。adapter 会在创建 compiler 前转换这些值，因为 Rstest 需要使用它们选择 test environment、解析 test module 或准备 build output。只有下表列出的 resolve 字段与 Rsbuild 共用；其他 Rspack resolver 选项由下一个表格中的流程处理。

其他选项仍会影响最终的 Rspack compilation，但不能安全地替换生成的 test 配置。adapter 会根据各选项的语义进行组合，例如追加 rules 和 plugins、合并 Rspack-only resolver 选项，并保留生成的 output path。Rstest 后续的 compiler hooks 仍可能恢复 test runtime 必需的值。

下一组选项不会与 Rstest 控制的 build 结构重叠，因此 adapter 会通过 Rsbuild 的 mergeConfig 将它们传给 compiler。该过程使用 Rspack 的标准 merge 语义，并以生成的配置为合并基础。数组和嵌套对象会遵循 Rspack 的常规 merge 行为，而不是由 adapter 另行定义赋值规则。

其余选项描述 application build、multi-compiler 或 dev server 工作流，或者控制由 Rstest 自己展示的输出。应用这些选项可能替换生成的 test 结构，或产生没有可观察效果的配置，因此 adapter 会继续让 Rstest 控制对应行为。extends 是一个例外：Rspack CLI 会在加载配置时消费它，所以 adapter 收到的是已经完成 merge 的结果，而不是继续向 compiler 传递 extends 字段。

Rspack 2.1 将原有的顶层 snapshot 选项移到了 cache.snapshot，因此它不再是顶层配置选项。Rspack persistent cache 会转换为 Rstest 生成的 build cache；cache.snapshot、maxAge、portable 和 readonly 等 Rspack-specific 调优字段不会复制到该生成缓存中。

#调试配置

设置 DEBUG=rstest 后，Rstest 会写入解析后的 Rstest、Rsbuild 和 Rspack 配置，并在命令输出中打印对应位置。检查生成的 Rspack 配置，可以确认哪些选项最终传给了 compiler：

DEBUG=rstest rstest

#相关文档

• Rspack 配置概览
• Rstest 配置概览