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

# 配置 Rspack

Rspack 提供了与 webpack 相似的配置项，通过本章节，你可以了解 Rspack 配置的使用方式。

## 配置文件

当你运行 Rspack 的命令行工具时，Rspack 会自动读取当前路径下的 `rspack.config.*` 文件。

一个基础的 Rspack 配置文件如下所示：


**ESM**

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

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```


**CJS**

```js title="rspack.config.cjs"
const { defineConfig } = require('@rspack/cli');

module.exports = defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```


**TypeScript**

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

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```


## 配置文件格式

Rspack 支持以下配置文件格式：

- `rspack.config.ts`: `TypeScript` 格式，参考 [TypeScript 配置文件](#typescript-配置文件) 了解更多。
- `rspack.config.js`: 默认为 `CommonJS` 格式，如果所在 package.json 的 type 为 "module" 则变成 `ES modules` 格式。
- `rspack.config.mts`: 强制为 `ES modules` + `TypeScript` 格式。
- `rspack.config.mjs`: 强制为 `ES modules` 格式。
- `rspack.config.cts`: 强制为 `CommonJS` + `TypeScript` 格式。
- `rspack.config.cjs`: 强制为 `CommonJS` 格式。

Rspack 默认会按以下顺序解析配置文件：

`rspack.config.ts` > `rspack.config.js` > `rspack.config.mts` > `rspack.config.mjs` > `rspack.config.cts` > `rspack.config.cjs`

> `CommonJS` 和 `ES modules`的区别请参考 [ES modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules) 和 [CommonJS](https://nodejs.org/api/modules.html)。

## 扩展配置

参考[扩展配置](/zh/config/extends.md)了解如何从其他文件或包中扩展配置。

## TypeScript 配置文件

在使用 `rspack.config.ts` 时，你可以选择以下任意一种方式：

### 默认行为

Rspack CLI 从 1.5.0 版本开始内置对 TypeScript 配置的支持。

默认情况下，Rspack CLI 使用 `--configLoader=auto`：

- JavaScript 配置文件使用运行时原生加载器。
- 当运行时原生支持 TypeScript 时，会优先尝试原生加载，失败后回退到 [Jiti](https://github.com/unjs/jiti)。
- 当运行时不支持原生 TypeScript 时，会直接使用 Jiti 加载 TypeScript 配置文件。

如果你使用的 Rspack CLI 版本小于 1.5.0，建议升级到最新版本。

### 原生支持

如果你使用的 JavaScript 运行时已经原生支持 TypeScript，你可以强制使用原生加载器来加载配置文件，确保模块解析行为与原生行为一致。

例如，Node.js 已经原生支持 TypeScript，你可以使用以下命令来使用 Node.js 原生加载器来加载配置文件：

- 对于原生支持 TypeScript 的 Node.js v22.18+ 和 v24.3+，你可以运行以下命令来加载 TS 配置：

```json title="package.json"
{
  "scripts": {
    "build": "rspack build --configLoader=native"
  }
}
```

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

### Jiti 加载器

你也可以强制使用 Jiti 来加载 TypeScript 配置文件：

```json title="package.json"
{
  "scripts": {
    "build": "rspack build --configLoader=jiti"
  }
}
```

### 配置类型检查

使用 `defineConfig` 工具函数来启用智能补全。对于 JavaScript 配置文件，你可以使用 `// @ts-check` 注释来启用类型检查。


**TypeScript**

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

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```


**JavaScript**

```js title="rspack.config.mjs"
// @ts-check
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```


你也可以使用 [JSDoc](https://jsdoc.app/) 来启用类型检查。

```js title="rspack.config.mjs"
// @ts-check
/** @type {import('@rspack/cli').Configuration} */
const config = {
  entry: {
    main: './src/index.js',
  },
};
export default config;
```

## 指定配置文件

Rspack 命令行支持通过 `--config` 选项来指定配置文件的名称。

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

```json title="package.json"
{
  "scripts": {
    "dev": "rspack serve",
    "build": "rspack build --config rspack.prod.config.js"
  }
}
```

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

```bash
$ rspack build -c rspack.prod.config.js
```

## 导出配置函数

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

```js title="rspack.config.mjs"
export default function (env, argv) {
  return {
    devtool: env.production ? 'source-map' : 'eval',
  };
}
```

从上述示例中可以看到，该函数接受两个入参：

- 第一个参数为 `env`，对应运行 CLI 命令时 `--env` 选项的值。
- 第二个参数为 `argv`，包含传递给 CLI 的所有选项。

### 判断当前环境

除了通过 `env` 参数，通过 `process.env.NODE_ENV` 来判断当前环境是更常见的方式：

```js title="rspack.config.mjs"
export default function (env, argv) {
  const isProduction = process.env.NODE_ENV === 'production';
  return {
    devtool: isProduction ? 'source-map' : 'eval',
  };
}
```

## 合并配置

使用 Rspack 的 [extends](/zh/config/extends.md) 选项或者 [rspack-merge](https://github.com/rstackjs/rspack-merge) 包来合并多个 Rspack 配置。

### extends 选项

在使用 [@rspack/cli](/zh/api/cli.md) 时，Rspack 提供了 `extends` 选项，允许你从其他文件或包中扩展配置。

```js title="rspack.config.mjs"
export default {
  extends: './base.rspack.config.mjs',
  output: {
    filename: '[name].bundle.js',
  },
};
```

> 该选项仅在 `@rspack/cli` 中有效，查看 [extends](/zh/config/extends.md) 了解更多用法。

### rspack-merge

`rspack-merge` 是一个库，用于合并多个 Rspack 配置。

首先安装 `rspack-merge`：


```sh [npm]
npm add rspack-merge -D
```

```sh [yarn]
yarn add rspack-merge -D
```

```sh [pnpm]
pnpm add rspack-merge -D
```

```sh [bun]
bun add rspack-merge -D
```

```sh [deno]
deno add npm:rspack-merge -D
```

然后你就可以使用它的 `merge` 函数来合并配置：

```js title="rspack.config.mjs"
import { merge } from 'rspack-merge';

const isDev = process.env.NODE_ENV === 'development';
const base = {};
const dev = {
  plugins: [new SomeDevPlugin()],
};

export default isDev ? merge(base, dev) : base;
```

> 查看 [rspack-merge 文档](https://github.com/rstackjs/rspack-merge) 了解更多。