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

# splitChunks

- **类型：**

```ts
type SplitChunksConfig =
  | (Rspack.OptimizationSplitChunksOptions & {
      preset?: SplitChunksPreset;
    })
  | false;
```

- **版本：** `>= 2.0.0`

`splitChunks` 用于配置 Rsbuild 的 chunk 拆分策略。

该选项基于 Rspack 的 [optimization.splitChunks](https://rspack.rs/zh/plugins/split-chunks-plugin) 实现，并在其基础上扩展了 `preset` 选项，用于启用 Rsbuild 提供的一组常用拆分预设。

## 默认行为 \{#default-behavior}

`splitChunks` 的默认值根据 [output.target](/zh/config/output/target.md) 而定。

### Web

- **默认值：** `{ preset: 'default', chunks: 'all' }`

对于 Web 构建，Rsbuild 会将 `chunks` 设置为 `'all'`。其余未指定的选项（如 `minSize` 和 `minChunks`）均沿用 Rspack [`optimization.splitChunks`](https://rspack.rs/zh/plugins/split-chunks-plugin) 的默认值。

:::tip
当项目作为 Module Federation provider 并配置 [`moduleFederation.options.exposes`](/zh/config/module-federation/options.md) 时，为避免 chunk 拆分影响 remote entry，Rsbuild 会将 `chunks` 设置为 `'async'`。
:::

### Node.js

- **默认值：**
  - 只有一个入口时：`{ preset: 'none', chunks: 'async', minSize: 0 }`
  - 有多个入口时：`{ preset: 'none', chunks: 'all', minSize: 0 }`

对于只有一个入口的 Node.js 构建，Rsbuild 会将 `chunks` 设置为 `'async'`，在不拆分初始入口 chunk 的情况下提取异步 chunk 之间的公共模块。对于有多个入口的 Node.js 构建，Rsbuild 会将 `chunks` 设置为 `'all'`，从而提取不同入口 chunk 使用的公共模块。

Rsbuild 还会将 `minSize` 设置为 `0`，使较小的共享模块也能被提取，避免这些模块重复出现在多个 chunk 中。

### Web worker

- **默认值：** `false`

当 [output.target](/zh/config/output/target.md) 为 `'web-worker'` 时，Rsbuild 默认关闭拆包。通过 `import()` 引用的模块也会打包到产物中，不会单独生成异步 chunk。

你可以通过 `splitChunks` 手动为 worker 提取共享 chunk。

## splitChunks.preset

- **类型：** `'default' | 'per-package' | 'single-vendor' | 'none' | undefined`
- **默认值：** `output.target` 为 `'web'` 时为 `'default'`，其他值时为 `'none'`

`preset` 用于启用 Rsbuild 内置的拆包预设，以简化常见的 chunk 拆分场景。

### default

Rsbuild 默认的拆包策略，包含如下规则：

- 启用 [output.polyfill](/zh/config/output/polyfill.md) 时，自动拆分 polyfill 代码到 `lib-polyfill.js`
- 注册 React 插件时，自动拆分 React 相关包到独立的 chunks，详见 [React 插件 - splitChunks](/zh/plugins/list/plugin-react.md#splitchunks)
- 注册 Vue 插件时，自动拆分 Vue 相关包到独立的 chunks，详见 [Vue 插件 - splitChunks](/zh/plugins/list/plugin-vue.md#splitchunks)

```ts title="rsbuild.config.ts"
export default {
  splitChunks: {
    preset: 'default',
  },
};
```

### per-package

`per-package` 会按照 npm 包粒度对 `node_modules` 中的依赖进行拆分，每个包对应一个独立的 chunk，生成类似 `npm-react.js` 或 `npm-babel_runtime.js` 的 chunk 名。

```ts title="rsbuild.config.ts"
export default {
  splitChunks: {
    preset: 'per-package',
  },
};
```

### single-vendor

`single-vendor` 会将 `node_modules` 中的所有第三方依赖合并到一个统一的 vendor chunk 中。

```ts title="rsbuild.config.ts"
export default {
  splitChunks: {
    preset: 'single-vendor',
  },
};
```

### none

`none` 会关闭 Rsbuild 内置的预设规则。当你希望使用 Rspack 的默认行为或仅使用自定义配置时可以使用。

```ts title="rsbuild.config.ts"
export default {
  splitChunks: {
    preset: 'none',
    // 其他自定义配置...
  },
};
```

## 其他选项

除 `preset` 之外，其余配置项的行为与 Rspack 的 `optimization.splitChunks` 保持一致，详细用法请参考 [Rspack 文档](https://rspack.rs/zh/plugins/split-chunks-plugin)。

```ts title="rsbuild.config.ts"
export default {
  splitChunks: {
    // Rsbuild 特有选项
    preset: 'default',
    // Rspack 提供的选项
    chunks: 'all',
    minSize: 20 * 1024,
    cacheGroups: {
      vendors: {
        test: /[\\/]node_modules[\\/]/,
        name: 'vendors',
        priority: -10,
      },
    },
  },
};
```

:::tip
Rsbuild 会先将预设规则转换为配置对象，再与你配置的 `splitChunks` 选项进行合并，用户配置的优先级更高。
:::

## 关闭 chunk 拆分 \{#disable-chunk-splitting}

如果你希望关闭 chunk 拆分，可以将 `splitChunks` 设置为 `false`：

```ts title="rsbuild.config.ts"
export default {
  splitChunks: false,
};
```

设置 `splitChunks: false` 后，动态 `import()` 引入的模块仍会生成独立的异步 chunk。若要将这些模块也打包到已有的 chunk 中，可以同时将 Rspack 的 [output.asyncChunks](https://rspack.rs/zh/config/output#outputasyncchunks) 设置为 `false`：

```ts title="rsbuild.config.ts"
export default {
  splitChunks: false,
  tools: {
    rspack: {
      output: {
        asyncChunks: false,
      },
    },
  },
};
```

对于单入口应用，这会将应用代码和动态导入的模块打包到同一个 JavaScript chunk 中。多入口应用仍会为每个入口生成独立的 chunk。

当 `output.target` 为 `'web-worker'` 时，默认不会生成异步 chunk，无需额外配置。

## 版本历史 \{#version-history}

| 版本     | 变更内容                                          |
| ------ | --------------------------------------------- |
| v2.2.0 | Node.js 构建默认启用 chunk 拆分，并将 `minSize` 设置为 `0`。 |