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

# Optimization

优化：该选项用于自定义优化配置。你可以通过 [optimization](/zh/config/optimization.md) 来自定义优化配置。默认情况下，Rspack 会根据 [mode](/zh/config/mode.md) 来选择合适的优化配置。

## optimization.avoidEntryIife


- 类型： `boolean`
- 默认值：`false`


使用 `optimization.avoidEntryIife` 可以避免在需要时将入口模块包装在 IIFE 中（在 [rspack\_plugin\_javascript](https://github.com/web-infra-dev/rspack/blob/main/crates/rspack_plugin_javascript/src/plugin/mod.rs) 中搜索 `"This entry needs to be wrapped in an IIFE because"`）。这种方法有助于优化 JavaScript 引擎的性能，并在构建 ESM 库时保证 tree shaking 生效。

目前，`optimization.avoidEntryIife` 只能优化单个入口模块及其他模块共存时的 IIFE。

```js title="rspack.config.mjs"
export default {
  optimization: {
    avoidEntryIife: true,
  },
};
```

:::warning
`optimization.avoidEntryIife` 选项可能会对构建性能产生负面影响，如果你更注重构建性能而不是这些优化，请考虑不要启用此选项。
:::

## optimization.chunkIds


- 类型： `false | 'natural' | 'named' | 'deterministic' | 'compact-hashed' | 'size' | 'total-size'`
- 默认值：[development 模式](/config/mode#development) 为`'named'`, [production 模式](/config/mode#production) 为`'deterministic'`


设置 Rspack 在生成 Chunk id 时使用的算法。

支持以下字符串值：

| 选项                 | 描述                                              |
| ------------------ | ----------------------------------------------- |
| `'natural'`        | 根据 Chunk 加载的顺序使用自增数字作为 Chunk id。                |
| `'named'`          | 使用有意义、方便调试的内容当作 Chunk id。                       |
| `'deterministic'`  | 简短的数字 id，在多次编译的场景下，会尽量保持其稳定性。适合长期缓存。默认使用 3 位数字。 |
| `'compact-hashed'` | 使用稳定小写字母数字 hash 的最短可用前缀。                        |
| `'size'`           | 使用让初始下载包大小更小的数字 id。                             |
| `'total-size'`     | 使用让总下载包大小更小的数字 id。                              |
| `false`            | 禁用 Rspack 内置的 Chunk id 算法，允许自定义插件提供 Chunk id。   |

```js title="rspack.config.mjs"
export default {
  optimization: {
    chunkIds: 'deterministic',
  },
};
```

`compact-hashed` 选项使用稳定小写字母数字 hash 的最短可用前缀作为 Chunk id，兼顾长期缓存、产物体积和运行时性能。

:::warning 已废弃的别名
`compat-hashed` 可在 Rspack 2.2.0 中使用，现已废弃，并于 Rspack 2.2.1 更名为 `compact-hashed`。旧名称目前仅作为兼容别名保留。
:::

```js title="rspack.config.mjs"
export default {
  optimization: {
    chunkIds: 'compact-hashed',
  },
};
```

:::tip
`compact-hashed` 选项从 Rspack 2.2.1 开始支持。
:::

## optimization.concatenateModules


- 类型： `boolean`
- 默认值：[production 模式](/config/mode#production) 为`true`, [development 模式](/config/mode#development) 为`false`


开启模块拼接优化，允许将多个模块拼接成单个模块以降低产物体积，提升压缩效率。此优化需要开启 [optimization.providedExports](#optimizationprovidedexports) 和 [optimization.usedExports](#optimizationusedexports)。默认情况下，`optimization.concatenateModules` 在 `production` 模式下启用，其它模式则禁用。

```js title="rspack.config.mjs"
export default {
  optimization: {
    concatenateModules: false,
  },
};
```

## optimization.emitOnErrors


- 类型： `boolean`
- 默认值：[production 模式](/config/mode#production) 为`false`, [development 模式](/config/mode#development) 为`true`


开启 `optimization.emitOnErrors` 时，即使编译过程中发生错误，Rspack 也会生成产物。这些错误会被注入到产物代码中，运行它们时会抛出错误。

```js title="rspack.config.mjs"
export default {
  optimization: {
    emitOnErrors: true,
  },
};
```

## optimization.inlineExports


[Added in v1.7.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.7.0)


- 类型： `boolean`
- 默认值：[production 模式](/config/mode#production) 为`true`, [development 模式](/config/mode#development) 为`false`


对以下内容执行跨模块内联优化：

1. 可被静态求值的顶层导出常量值：
   - `null` 或 `undefined`
   - `boolean` 值（`true` 或 `false`）
   - 长度 \<= 6 的 `number`
   - 长度 \<= 6 的 `string`

2. 由 [`builtin:swc-loader collectTypeScriptInfo.exportedEnum`](/zh/guide/features/builtin-swc-loader.md#collecttypescriptinfoexportedenum) 收集的导出 TypeScript 枚举

这个优化有助于减少产物体积并可以提升运行时性能。

常见的使用场景是 `constants.js` 文件：

```js
// constants.js
export const A = true;
export const B = 'hello';

// index.js
import { A, B } from './constants';
console.log(A ? 1 : 2);
console.log(B.length);
```

当启用 `inlineExports` 时，常量值将被内联到使用位置：

```js
// 由 Rspack 打包后的输出：output.js
const __webpack_modules__ = {
  './index.js': () => {
    // 常量被直接内联
    console.log(true ? 1 : 2);
    console.log('hello'.length);
    // 如果 constants.js 的所有导出都被内联，该模块将被优化掉，
    // 不会出现在最终产物中
  },
};
```

:::tip
由于此功能依赖模块导出使用信息（[optimization.usedExports](#optimizationusedexports)），建议仅在生产模式下启用，因为生产模式下 `usedExports` 默认启用。
:::

:::warning TDZ 行为
内联循环引用模块中的常量导出，可能会让原本会触发暂时性死区（TDZ）错误的代码不再报错。生态中大多数工具通常在进行优化时不会保留 TDZ 错误；Rspack 也遵循这种优化优先的行为。
:::

更多详情，请参考 [inline const 示例](https://github.com/rstackjs/rstack-examples/tree/main/rspack/inline-const)。

## optimization.innerGraph


- 类型： `boolean`
- 默认值：[production 模式](/config/mode#production) 为`true`, [development 模式](/config/mode#development) 为`false`


`optimization.innerGraph` 告诉 Rspack 是否对变量传递进行更详细的分析，这有助于 Rspack 识别未使用的模块导出，从而减少打包产物的体积。

例如：

```js
import { value } from 'lib';

const value2 = value;

function f1() {
  console.log(value);
}

function f2() {
  console.log(value2);
}
```

这里我们将 `value` 赋值给了 `value2`，`value2` 和 `value` 也分别在函数 `f2` 和 `f1` 中被访问，但函数没有被调用，因此没有使用到 `value2` 和 `value`，因此 `value` 的导入是可以被删除的。

## optimization.mangleExports


- 类型： `boolean | 'deterministic' | 'size'`
- 默认值：[production 模式](/config/mode#production) 为`true`, [development 模式](/config/mode#development) 为`false`


`optimization.mangleExports` 用于控制导出名的混淆方式。

支持以下选项：

| option            | description                           |
| ----------------- | ------------------------------------- |
| `'size'`          | 使用尽可能短的导出名，以减小产物体积。                   |
| `'deterministic'` | 使用短且稳定的导出名，以获得更好的长期缓存稳定性。生产模式默认启用该选项。 |
| `true`            | 与 `'deterministic'` 相同。               |
| `false`           | 关闭导出名混淆，保留原始导出名。开发模式默认启用该选项。          |

例如源代码为：

```js title="src/math.js"
export const veryLongExportName = 1;
```

关闭 `mangleExports` 时，导出名会被保留：

```js title="dist/main.js"
__webpack_require__.d(__webpack_exports__, {
  veryLongExportName: () => veryLongExportName,
});
```

将 `mangleExports` 设置为 `'size'` 时，导出名会被缩短：

```js title="rspack.config.mjs"
export default {
  optimization: {
    mangleExports: 'size',
  },
};
```

```js title="dist/main.js"
__webpack_require__.d(__webpack_exports__, {
  a: () => veryLongExportName,
});
```

## optimization.mergeDuplicateChunks


- 类型： `boolean`
- 默认值：`true`


是否合并重复的 chunks，将 `optimization.mergeDuplicateChunks` 设置成 `false` 来关闭该优化。

```js title="rspack.config.mjs"
export default {
  optimization: {
    mergeDuplicateChunks: false,
  },
};
```

## optimization.minimize


- 类型： `boolean`
- 默认值：[production 模式](/config/mode#production) 为`true`, [development 模式](/config/mode#development) 为`false`


是否使用 [`optimization.minimizer`](#optimizationminimizer) 中声明的压缩器对产物进行压缩。

```js title="rspack.config.mjs"
export default {
  optimization: {
    minimize: true,
  },
};
```

## optimization.minimizer


- 类型： `('...' | Plugin)[]`
- 默认值：`[new SwcJsMinimizerRspackPlugin(), new LightningCssMinimizerRspackPlugin()]`


自定义压缩器。默认使用 [`rspack.SwcJsMinimizerRspackPlugin`](/zh/plugins/swc-js-minimizer-rspack-plugin.md) 和 [`rspack.LightningCssMinimizerRspackPlugin`](/zh/plugins/lightning-css-minimizer-rspack-plugin.md)。

当设置了 `optimization.minimizer` 时，默认的压缩器会被禁用。

```js title="rspack.config.mjs"
import TerserPlugin from 'terser-webpack-plugin';

export default {
  optimization: {
    minimizer: [new TerserPlugin()],
  },
};
```

使用 Rspack 内置的压缩器，并自定义压缩选项：

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

export default {
  optimization: {
    // 当声明了 `optimization.minimizer`，默认压缩器会被禁用
    // 但你可以配合使用 '...'，它代表默认压缩器
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        minimizerOptions: {
          format: {
            comments: false,
          },
        },
      }),
      new rspack.LightningCssMinimizerRspackPlugin({
        minimizerOptions: {
          errorRecovery: false,
        },
      }),
    ],
  },
};
```

## optimization.moduleIds


- 类型： `false | 'natural' | 'named' | 'deterministic' | 'compact-hashed' | 'hashed'`
- 默认值：[production 模式](/config/mode#production) 为`'deterministic'`, [development 模式](/config/mode#development) 为`'named'`, [none 模式](/config/mode#none) 为`'natural'`


设置 Rspack 在生成模块 id 时使用的算法。

支持以下字符串值：

| 选项               | 描述                                                                         |
| ---------------- | -------------------------------------------------------------------------- |
| `natural`        | 根据模块加载的顺序使用自增数字作为模块 id。                                                    |
| `named`          | 使用有意义、方便调试的内容当作模块 id。                                                      |
| `deterministic`  | 使用对模块标识符哈希后的数字当作模块 id，有益于长期缓存。默认使用 3 位数字。                                  |
| `compact-hashed` | 使用稳定字母数字 hash 的最短可用前缀。                                                     |
| `hashed`         | 使用模块标识符的哈希值作为模块 id。等同于使用默认选项（md4、base64、4 字符）的 `HashedModuleIdsPlugin` 插件。 |
| `false`          | 禁用 Rspack 内置的模块 id 算法，允许自定义插件提供模块 id。                                      |

推荐在开发环境使用 `named`，在生产环境使用 `deterministic` 或 `compact-hashed`。

通过 `process.env.NODE_ENV` 来判断当前环境：

```js title="rspack.config.mjs"
const isDev = process.env.NODE_ENV === 'development';

export default {
  optimization: {
    moduleIds: isDev ? 'named' : 'deterministic',
  },
};
```

`compact-hashed` 选项使用稳定字母数字 hash 的最短可用前缀作为模块 id，兼顾长期缓存、产物体积和运行时性能。

:::warning 已废弃的别名
`compat-hashed` 可在 Rspack 2.2.0 中使用，现已废弃，并于 Rspack 2.2.1 更名为 `compact-hashed`。旧名称目前仅作为兼容别名保留。
:::

:::warning
`compact-hashed` 生成的模块 id 区分大小写且可能包含大写字母。在大小写不敏感的文件系统上，不要在 [Asset module 文件名](/zh/config/output.md#outputassetmodulefilename)或 [WebAssembly 模块文件名](/zh/config/output.md#outputwebassemblymodulefilename)中仅使用 `[id]` 进行区分。请优先使用 `[contenthash]`，或将其与 `[id]` 一起使用。
:::

```js title="rspack.config.mjs"
const isDev = process.env.NODE_ENV === 'development';

export default {
  optimization: {
    moduleIds: isDev ? 'named' : 'compact-hashed',
  },
};
```

:::tip
`compact-hashed` 选项从 Rspack 2.2.1 开始支持。
:::

## optimization.nodeEnv

- **类型：** `string | false`
- **默认值：** 由 [`mode`](/zh/config/mode.md) 决定：
  - [`production` 模式](/zh/config/mode.md#production)：`'production'`
  - [`development` 模式](/zh/config/mode.md#development)：`'development'`
  - [`none` 模式](/zh/config/mode.md#none)：`false`

`optimization.nodeEnv` 用于控制 Rspack 在编译时替换 `process.env.NODE_ENV` 所使用的值。Rspack 会通过 [DefinePlugin](/zh/plugins/define-plugin.md) 完成该替换。

你也可以使用以下值覆盖由 `mode` 决定的默认行为：

- 任意字符串：将 `process.env.NODE_ENV` 替换为指定的字符串。
- `false`：禁用替换，保留代码中的 `process.env.NODE_ENV`。

```js title="rspack.config.mjs"
export default {
  optimization: {
    nodeEnv: 'production',
  },
};
```

## optimization.providedExports


- 类型： `boolean`
- 默认值：`true`


开启后 Rspack 将会分析模块提供哪些导出，包括重导出模块，引用模块不存在的导出时会发出提示。默认情况下，`optimization.providedExports` 已启用，该分析会增加构建时间，你可以考虑在 development 模式中关闭该配置，关闭后有可能会遇到[SideEffects 章节](/zh/guide/optimization/tree-shaking.md#重导出分析)运行时循环依赖的错误。

```js title="rspack.config.mjs"
export default {
  optimization: {
    providedExports: false,
  },
};
```

## optimization.realContentHash


- 类型： `boolean`
- 默认值：[production 模式](/config/mode#production) 为`true`, [development 模式](/config/mode#development) 为`false`


在产物处理完成后，添加额外的哈希计算步骤根据产物的文件内容计算该产物的哈希。该功能在生产环境下会默认开启。

如果将 `realContentHash` 设置为 `false`，则使用编译流程中的内部数据计算哈希，在某些情况下，即使产物内容完全一致也可能导致哈希变化。

```js title="rspack.config.mjs"
export default {
  optimization: {
    realContentHash: true,
  },
};
```

## optimization.removeEmptyChunks


- 类型： `boolean`
- 默认值：`true`


检测并移除打包过程中产生的空 Chunk。将 `optimization.removeEmptyChunks` 设置为 `false` 来禁用该优化。

```js title="rspack.config.mjs"
export default {
  optimization: {
    removeEmptyChunks: false,
  },
};
```

## optimization.runtimeChunk


- 类型： `boolean | 'single' | 'multiple' | { name?: string | ((entrypoint: { name: string }) => string) }`
- 默认值：`false`


用来控制 Rspack 的 [runtime](/zh/misc/glossary.md#runtime) chunk 如何生成。

默认为 `false`，这意味着运行时代码会被内联到入口的 chunks 中。

设置为 `true` 或 `'multiple'` 会为每个入口添加一个仅包含运行时的额外 chunk。该设置等同于：

```js title="rspack.config.mjs"
export default {
  optimization: {
    runtimeChunk: {
      name: (entrypoint) => `runtime~${entrypoint.name}`,
    },
  },
};
```

设置为 `'single'` 会将所有入口的运行时代码抽离到一个名为 `runtime` 的单独 chunk。该设置等同于：

```js title="rspack.config.mjs"
export default {
  optimization: {
    runtimeChunk: {
      name: 'runtime',
    },
  },
};
```

设置为对象时，可以提供可选的 `name` 属性，该属性代表 runtime chunk 的名称。

```js title="rspack.config.mjs"
export default {
  optimization: {
    runtimeChunk: {
      // 这将生成一个名为 `my-name.js` 的 chunk
      name: 'my-name',
    },
  },
};
```

:::tip
被导入的模块在每个 runtime chunk 中是单独初始化的，因此，如果你在单个页面中包含多个入口 chunks，请留意这种行为。你需要将 `optimization.runtimeChunk` 设置为 `'single'` 或使用其他配置，以保证页面仅包含一个 runtime 实例。
:::

## optimization.sideEffects


- 类型： `boolean | 'flag'`
- 默认值：[production 模式](/config/mode#production) 为`true`, [development 模式](/config/mode#development) 为`'flag'`


如果你只希望 Rspack 使用手动指定的 `sideEffects` 标志（通过 `package.json` 和 `rules[].sideEffects`），而不分析源代码，可以这样配置：

```js title="rspack.config.mjs"
export default {
  optimization: {
    sideEffects: 'flag',
  },
};
```

配置为 `flag` 会让 Rspack 仅识别 package.json 中的 `sideEffects` 标志或者 [`rules[].sideEffects`](/zh/config/module-rules.md#rulessideeffects)（模块配置中的规则），以跳过那些被标记为没有副作用但未被使用的模块。

配置为 `true` 会让 Rspack 除了识别用户主动标记以外，还会尝试分析未被标记的 module 源码是否包含副作用。

```js title="rspack.config.mjs"
export default {
  optimization: {
    sideEffects: true,
  },
};
```

:::tip
`optimization.sideEffects` 依赖于启用 [`optimization.providedExports`](#optimizationprovidedexports)。这在构建时会有一定的成本，但消除模块对性能有积极的影响，因为生成的代码更少。这个优化的效果取决于你的代码库，尝试使用它来获得可能的性能提升。
:::

## optimization.splitChunks


- 类型： `false | object`


Rspack 支持通过 `optimization.splitChunks` 配置项来对 Chunk 进行拆分。

该优化选项默认情况下是开启的，你可以将其设为 `false` 来关闭它。

有关配置此行为的可用选项，请参见 [SplitChunksPlugin](/zh/plugins/split-chunks-plugin.md) 页面。

## optimization.usedExports


- 类型： `boolean | 'global'`
- 默认值：[production 模式](/config/mode#production) 为`true`, [development 模式](/config/mode#development) 为`false`


告诉 Rspack 对每个模块确定使用的导出。这取决于 `optimization.providedExports`。
`optimization.usedExports` 收集的信息被其他优化或代码生成使用，即不会为未使用的导出生成导出信息，当所有用法兼容时，导出名称会被缩短为单个字符标识符。压缩器中的死代码消除将受益于此，并且可以删除未使用的导出。

```js title="rspack.config.mjs"
export default {
  optimization: {
    usedExports: false,
  },
};
```

如果需要在运行时取消使用的导出分析：

```js title="rspack.config.mjs"
export default {
  optimization: {
    usedExports: 'global',
  },
};
```


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