#splitChunks

• 类型：

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

• 版本： >= 2.0.0

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

该选项基于 Rspack 的 optimization.splitChunks 实现，并在其基础上扩展了 preset 选项，用于启用 Rsbuild 提供的一组常用拆分预设。

#默认行为

splitChunks 的默认值根据 output.target 而定。

#Web

• 默认值： { preset: 'default', chunks: 'all' }

对于 Web 构建，Rsbuild 会将 chunks 设置为 'all'。其余未指定的选项（如 minSize 和 minChunks）均沿用 Rspack optimization.splitChunks 的默认值。

#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

由于 Web Worker 产物不支持 dynamic import，当 output.target 为 'web-worker' 时，Rsbuild 默认关闭 chunk 拆分。

#splitChunks.preset

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

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

#default

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

• 启用 output.polyfill 时，自动拆分 polyfill 代码到 lib-polyfill.js
• 注册 React 插件时，自动拆分 React 相关包到独立的 chunks，详见 React 插件 - splitChunks
• 注册 Vue 插件时，自动拆分 Vue 相关包到独立的 chunks，详见 Vue 插件 - splitChunks

export default {
  splitChunks: {
    preset: 'default',
  },
};

#per-package

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

export default {
  splitChunks: {
    preset: 'per-package',
  },
};

#single-vendor

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

export default {
  splitChunks: {
    preset: 'single-vendor',
  },
};

#none

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

export default {
  splitChunks: {
    preset: 'none',
    // 其他自定义配置...
  },
};

#其他选项

除 preset 之外，其余配置项的行为与 Rspack 的 optimization.splitChunks 保持一致，详细用法请参考 Rspack 文档。

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

#关闭 chunk 拆分

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

export default {
  splitChunks: false,
};

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

export default {
  splitChunks: false,
  tools: {
    rspack: {
      output: {
        asyncChunks: false,
      },
    },
  },
};

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

#版本历史