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

# Target

`target` 用于描述输出代码的运行环境。Rspack 会据此确定目标环境支持的平台 API 和 ECMAScript 语法，并自动设置与该环境兼容的模块解析条件、externals 预设和 chunk 加载方式。Rspack 生成的 runtime 代码也会使用目标环境支持的语法。

当 Rspack 内置的 loader 和压缩插件未显式配置目标时，它们也可以从 `target` 继承默认值。但 `target` 不会为缺失的 API 注入 polyfill。

- **类型：**

```ts
type Target = false | string | string[];
```

- **默认值：** 当项目中包含标准的 Browserslist 配置时为 `browserslist`，否则为 `web`

## 推荐配置

### 浏览器

对于浏览器应用，在共享的 [Browserslist](https://github.com/browserslist/browserslist#config-file) 配置中声明需要支持的浏览器（详见 [Browserslist](#browserslist) 小节）：

```json title="package.json"
{
  "browserslist": ["fully supports es6"]
}
```

使用以下配置：

```js title="rspack.config.mjs"
export default {
  target: 'browserslist',
};
```

当项目中包含标准的 Browserslist 配置时，`target` 默认就是 `browserslist`，因此可以省略这一选项。显式保留可以让配置意图更清晰。

#### 固定语法版本

如果不使用 Browserslist，并且希望浏览器产物的 runtime 最多使用 ES2020 语法，可以组合平台和语法 target（详见 [Target 数组](#target-arrays)）：

```js title="rspack.config.mjs"
export default {
  target: ['web', 'es2020'],
};
```

`web` 用于选择平台。`es2020` 会限制 Rspack runtime 使用的语法；支持继承 `target` 的内置转换工具也会将它作为默认输出目标。

### Node.js

对于 Node.js 应用，指定部署环境中使用的最低 Node.js 版本：

```js title="rspack.config.mjs"
export default {
  target: 'node22',
};
```

请将 `22` 替换为应用实际支持的版本。指定版本后，Rspack 可以使用该版本确定支持的 runtime 特性。不指定版本的 `node` 会采用更保守的兼容性假设。

### Web worker

对于运行在 Web Worker、Shared Worker 或 Service Worker 中的代码，使用：

```js title="rspack.config.mjs"
export default {
  target: 'webworker',
};
```

该配置会使用 worker 全局对象和 chunk 加载方式，而不依赖 `document` 等浏览器 API。

## 常用值

下表中的 `X` 和 `Y` 表示版本号，方括号表示可选部分。例如，`node22`、`node22.12` 和 `electron34-renderer` 都是有效值，不需要输入方括号。

| 值                          | 用途                                             |
| -------------------------- | ---------------------------------------------- |
| `async-node[X[.Y]]`        | Node.js 环境，通过 `fs` 和 `vm` 异步加载 chunk           |
| `browserslist[:...]`       | 从 Browserslist 配置、环境或内联查询中推断平台和支持的特性           |
| `electron[X[.Y]]-main`     | Electron 主进程                                   |
| `electron[X[.Y]]-preload`  | Electron preload 脚本                            |
| `electron[X[.Y]]-renderer` | Electron renderer 进程                           |
| `esX`                      | 限制 runtime 使用的 ECMAScript 特性，通常与平台 target 组合使用 |
| `false`                    | 禁用 target 推断以及由 target 派生的默认值                  |
| `node[X[.Y]]`              | Node.js 环境，通过 `require()` 加载 chunk             |
| `node-webkit[X[.Y]]`       | 对应 NW\.js target 的别名                           |
| `nwjs[X[.Y]]`              | NW\.js 环境                                      |
| `web`                      | 类浏览器环境                                         |
| `webworker`                | Web Worker、Shared Worker 或 Service Worker 环境   |

- 支持的 ECMAScript target 包括 `es3`、`es5`，以及 `es2015` 至 `es2025`。
- `esX` target 只描述语法能力，不描述运行平台。通常它应该与 `web`、`node` 等平台 target 组合使用。
- Node.js、Electron 和 NW\.js target 都可以指定版本。

## 作用范围

### 输出默认值

Rspack 会从 target 派生多项默认配置，包括：

- `browser`、`node` 和 `electron` 等[模块解析条件](/zh/config/resolve.md#resolveconditionnames)
- [`output.environment`](/zh/config/output.md#outputenvironment)、chunk 格式、chunk 加载、worker 加载和 WebAssembly 加载方式
- [externals 预设](/zh/config/externals.md#externalspresets)，例如将 Node.js 或 Electron 内置模块保留为 external
- `document`、`require`、`global` 和 `importScripts` 等平台全局对象与能力

这些配置都是默认值。当 target 预设不符合某项具体输出要求时，可以单独覆盖对应选项。

### 源码转换 \{#目标环境继承}

`target` 会直接控制 Rspack 生成的 runtime 可以使用哪些语法，但它本身不会自动降级每一个应用模块的语法。

使用以下内置工具且没有显式配置转换目标时，它们会从 `target` 继承兼容的默认值：

- [`builtin:swc-loader`](/zh/guide/features/builtin-swc-loader.md) 会派生 `env.targets` 或 `jsc.target`
- [`builtin:lightningcss-loader`](/zh/guide/features/builtin-lightningcss-loader.md) 会在存在浏览器目标时派生对应的 target
- [`SwcJsMinimizerRspackPlugin`](/zh/plugins/swc-js-minimizer-rspack-plugin.md) 会派生 ECMAScript target
- [`LightningCssMinimizerRspackPlugin`](/zh/plugins/lightning-css-minimizer-rspack-plugin.md) 会在存在浏览器目标时派生对应的 target

只有经过这些工具处理的代码才会应用相应转换。由 Babel 处理的代码遵循 Babel 自身的配置。内置工具也可能将继承的 target 限制在自身支持的版本范围内。

## Target 数组 \{#target-arrays}

target 数组会将所有值共同支持的特性子集应用于同一次编译。常见用法是在平台 target 上增加 ECMAScript 约束：

```js title="rspack.config.mjs"
export default {
  target: ['web', 'es2018'],
};
```

target 数组不会为每个环境创建独立的编译任务。组合 `['web', 'node']` 等存在冲突的平台 target，可能导致 chunk 格式等默认值无法确定。

如果需要分别生成浏览器和 Node.js 产物，应导出多份配置：

```js title="rspack.config.mjs"
export default [
  {
    name: 'client',
    entry: './src/client.js',
    target: 'web',
    output: {
      filename: 'client.js',
    },
  },
  {
    name: 'server',
    entry: './src/server.js',
    target: 'node22',
    output: {
      filename: 'server.js',
    },
  },
];
```

Rspack 会通过 [MultiCompiler](/zh/api/javascript-api/compiler.md#multicompiler) 运行这些配置，并为每一项创建独立的编译任务。

## Browserslist

`browserslist` target 会通过 Browserslist 查询推断平台以及支持的 ECMAScript 特性。浏览器查询会选择 `web` target，Node.js 查询则会选择具备对应 runtime 能力的 Node.js target。

Rspack 支持以下格式：

| 值                                     | 解析方式                   |
| ------------------------------------- | ---------------------- |
| `browserslist`                        | 使用最近的配置及其当前环境          |
| `browserslist:modern`                 | 使用最近配置中的 `modern` 环境   |
| `browserslist:last 2 versions`        | 使用内联查询，并忽略项目中的配置       |
| `browserslist:/path/to/config`        | 使用指定的配置文件              |
| `browserslist:/path/to/config:modern` | 使用指定配置文件中的 `modern` 环境 |

最近的配置可以来自 `browserslist` 或 `.browserslistrc` 文件，也可以来自 `package.json` 中的 `browserslist` 字段。显式选择 `browserslist` target 时，还可以使用 `BROWSERSLIST` 环境变量。Rspack 支持浏览器和 Node.js 查询，但不支持 Electron 查询。

### Baseline \{#baseline-queries}

Rspack 2.1.9 及更高版本支持 [Baseline](https://web.dev/baseline) 查询。例如，以下 target 包含支持 Baseline Widely Available 中所有特性的浏览器：

```js title="rspack.config.mjs"
export default {
  target: 'browserslist:baseline widely available',
};
```

你也可以使用 `baseline 2024` 等年份查询，或 `baseline widely available on 2025-05-01` 等固定日期查询。更多信息请参考[在 Browserslist 中使用 Baseline](https://web.dev/articles/use-baseline-with-browserslist)。

### 限制

Rspack 使用 [browserslist-rs](https://github.com/browserslist/browserslist-rs)，它尚未实现 Browserslist 的全部功能。目前不支持以下查询：

- 自定义使用率查询，例如 `> 0.5% in my stats`
- 覆盖率查询，例如 `cover 99.5% in my stats`

## 禁用 target

仅在需要用自定义配置替代 target 推断时，才将 `target` 设为 `false`。这会禁用所有由 target 派生的默认值。

以下是使用 CommonJS chunk 格式的最小配置：

```js title="rspack.config.mjs"
export default {
  target: false,
  output: {
    chunkFormat: 'commonjs',
  },
};
```

只配置 `target: false` 会构建失败，因为 Rspack 无法推断 [`output.chunkFormat`](/zh/config/output.md#outputchunkformat)。必须显式设置 `output.chunkFormat`，然后根据运行环境按需配置 `output.environment`、chunk 加载、解析条件和 externals 预设等选项。

## 相关配置

- [`output.environment`](/zh/config/output.md#outputenvironment)：覆盖从 target 派生的 runtime 语法能力。
- [`output.chunkFormat`](/zh/config/output.md#outputchunkformat) 和 [`output.chunkLoading`](/zh/config/output.md#outputchunkloading)：覆盖 chunk 的输出与加载方式。
- [`externalsPresets`](/zh/config/externals.md#externalspresets)：控制哪些平台内置模块被视为 external。
- [`resolve.conditionNames`](/zh/config/resolve.md#resolveconditionnames)：控制解析 `package.json` 中的 `exports` 字段时使用的条件。
- 插件作者可以通过 [`compiler.target`](/zh/api/javascript-api/compiler.md#target) 读取解析后的 target。


本页改编自 [webpack 文档](https://webpack.js.org/configuration/target/)，遵循 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)，且已作修改。