> 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

Rsbuild 提供了丰富的配置项，并为每个配置项预设了一个通用的默认值，它可以满足大部分使用场景。因此，在大多数情况下，你不需要声明任何 Rsbuild 配置，直接开箱使用即可。

如果你需要定制一些构建行为，那么可以使用这些配置项。

## 配置结构

Rsbuild 的配置结构如下所示：

```js title="rsbuild.config.mjs"
export default {
  plugins: [
    // 配置 Rsbuild 插件
  ],
  dev: {
    // 与本地开发有关的选项
  },
  html: {
    // 与 HTML 生成有关的选项
  },
  tools: {
    // 与底层工具有关的选项
  },
  output: {
    // 与构建产物有关的选项
  },
  resolve: {
    // 与模块解析相关的选项
  },
  source: {
    // 与输入的源代码相关的选项
  },
  server: {
    // 与 Rsbuild 服务器有关的选项
    // 主要用于本地开发和预览
    // 部分选项（如 publicDir、base）也会影响生产构建
  },
  security: {
    // 与 Web 安全有关的选项
  },
  performance: {
    // 与构建性能、运行时性能有关的选项
  },
  moduleFederation: {
    // 与模块联邦有关的选项
  },
  environments: {
    // 为每个环境定义不同的 Rsbuild 配置
  },
};
```

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

## 配置文件

当你使用 Rsbuild 的 CLI 命令时，或者在未指定 `path` 的情况下调用 `loadConfig` 时，Rsbuild 会自动读取当前项目根目录下的配置文件，并按以下顺序进行解析：

- rsbuild.config.ts
- rsbuild.config.js
- rsbuild.config.mts
- rsbuild.config.mjs
- rsbuild.config.cts
- rsbuild.config.cjs

如果同时存在多个配置文件，Rsbuild 会使用这个列表中第一个匹配到的文件。

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

比如在 `rsbuild.config.ts` 中，你可以定义 Rsbuild 的 [resolve.alias](/zh/config/resolve/alias.md) 配置：

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

export default defineConfig({
  resolve: {
    alias: {
      '@common': './src/common',
    },
  },
});
```

:::tip
如果 Node.js 在加载 `rsbuild.config.ts` 时出现 `[MODULE_TYPELESS_PACKAGE_JSON]` 警告，你可以在 package.json 中添加 `"type": "module"`，或将文件重命名为 `rsbuild.config.mts` 来解决该警告。
:::

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

```js title="rsbuild.config.mjs"
import { defineConfig } from '@rsbuild/core';

export default defineConfig({
  resolve: {
    alias: (opts) => {
      opts['@common'] = './src/common';
    },
  },
});
```

## 指定配置文件 \{#specify-config-file}

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

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

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

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

```bash
rsbuild build -c rsbuild.prod.config.mjs
```

## 指定加载方式 \{#specify-config-loader}

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

- `auto`（默认）：优先使用 Node.js 原生 loader 来加载配置文件，失败时回退到使用 jiti 加载。
- `jiti`：使用 [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 rsbuild build --config-loader native

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

### 关于 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 './rsbuild.base.config.ts'; // ✅ 正确
   import baseConfig from './rsbuild.base.config'; // ❌ 错误
   ```

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

## 使用环境变量

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

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

export default defineConfig({
  resolve: {
    alias: {
      '@request':
        process.env.NODE_ENV === 'development'
          ? './src/request.dev.js'
          : './src/request.prod.js',
    },
  },
});
```

## 导出配置函数

Rsbuild 支持在配置文件中导出一个函数，你可以在函数中动态计算配置，并返回给 Rsbuild。

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

export default defineConfig(({ env, command, envMode }) => ({
  resolve: {
    alias: {
      '@foo': env === 'development' ? './src/foo.dev.ts' : './src/foo.prod.ts',
    },
  },
}));
```

:::tip
导出的配置函数必须提供一个返回值，如果你不需要返回任何配置，可以 return 一个空对象。
:::

该函数接受以下入参：

### env

- **类型：** `string`
- **默认值：** `process.env.NODE_ENV`

当前运行的环境。

- 运行 `rsbuild dev` 时，env 的默认值为 `development`。
- 运行 `rsbuild build` 或 `rsbuild preview` 时，env 的默认值为 `production`。

### envMode

- **类型：** `string`
- **默认值：** `process.env.NODE_ENV`

CLI 参数 `--env-mode` 当前的值。

比如，当运行 `rsbuild build --env-mode test` 时，`envMode` 的值为 `test`。

### command

- **类型：** `string`

当前运行的 CLI 命令，如 `dev`、`build`、`preview`。

## 导出异步函数

Rsbuild 也支持在配置文件中导出一个异步函数，你可以在函数中进行一些异步操作：

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

export default defineConfig(async ({ env, command }) => {
  const result = await someAsyncFunction();

  return {
    html: {
      title: result,
    },
  };
});
```

## 合并配置

你可以使用 `@rsbuild/core` 导出的 [mergeRsbuildConfig](/zh/api/javascript-api/core.md#mergersbuildconfig) 函数来合并多个配置。

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

const config1 = defineConfig({
  dev: { port: '3000' },
});
const config2 = defineConfig({
  dev: { port: '3001' },
});

// { dev: { port: '3001' }
export default mergeRsbuildConfig(config1, config2);
```

## 配置文件监听 \{#configuration-file-watching}

### Rsbuild CLI

使用 Rsbuild CLI 时，`rsbuild dev` 和 `rsbuild build --watch` 会自动监听已加载的配置文件及其导入依赖。

当其中任一文件发生变化时，Rsbuild 会重新加载配置，并重启当前 dev server 或监听构建。

### JavaScript API

使用 JavaScript API 时，请将 [`loadConfig`](/zh/api/javascript-api/core.md#loadconfig) 的完整返回结果传入 `createRsbuild`。Rsbuild 会据此追踪配置文件及其导入依赖。

调用 `rsbuild.startDevServer()`、`rsbuild.createDevServer()` 或 `rsbuild.build({ watch: true })` 时，Rsbuild 会安装 restart 监听器，并自动监听上述文件；普通构建和预览服务器不会安装监听器。被监听的文件发生变化时，Rsbuild 会调用 [onRestart hook](/zh/plugins/dev/hooks.md#onrestart)。

默认情况下，Rsbuild 仅调用该 hook，不会自动重启当前任务。如需执行重启流程，可以传入 [`restart` 选项](/zh/api/javascript-api/core.md#restart-handling)。

## 调试配置

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

```bash
DEBUG=rsbuild pnpm dev
```

在调试模式下，Rsbuild 会将内部最终生成的 Rsbuild 配置写入到产物目录下，便于开发者查看和调试。

```
config inspection completed, generated files:

  - Rsbuild config: /Project/demo/dist/.rsbuild/rsbuild.config.mjs
  - Rspack config (web): /Project/demo/dist/.rsbuild/rspack.config.web.mjs
```

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

关于调试模式的完整介绍，请查看 [开启调试模式](/zh/guide/debug/debug-mode.md) 章节。