SplitChunksPlugin#

默认值#

开箱即用的 SplitChunksPlugin 对于大部分用户来说非常友好。

默认情况下，它只会影响到按需加载的 chunk，因为初始 chunk 会影响到项目的 HTML 文件中的脚本标签。

rspack 将根据以下条件自动拆分 chunk：

• 新的 chunk 可以被共享，或者模块来自于 node_modules 文件夹
• 新的 chunk 体积大于 20kb（在进行 min+gz 之前的体积）
• 当按需加载 chunks 时，并行请求的最大数量小于或等于 30
• 当加载初始化页面时，并发请求的最大数量小于或等于 30

配置#

rspack 为希望对该功能进行更多控制的开发者提供了一组选项。

optimization.splitChunks#

下面这个配置对象代表 SplitChunksPlugin 的默认行为。

module.exports = {
  //...
  optimization: {
    splitChunks: {
      chunks: 'async',
      minChunks: 1,
      minSize: 20000,
      maxAsyncRequests: 30,
      maxInitialRequests: 30,
      cacheGroups: {
        defaultVendors: {
          test: /[\\/]node_modules[\\/]/,
          priority: -10,
          reuseExistingChunk: true,
        },
        default: {
          minChunks: 2,
          priority: -20,
          reuseExistingChunk: true,
        },
      },
    },
  },
};

splitChunks.cacheGroups#

缓存组可以继承和/或覆盖来自 splitChunks.{cacheGroup}.* 的任何选项。但是 test、priority 和 reuseExistingChunk 只能在缓存组级别上进行配置。将它们设置为 false 以禁用任何默认缓存组。

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        default: false,
      },
    },
  },
};

splitChunks.chunks#

splitChunks.cacheGroups.{cacheGroup}.chunks#

• 类型： string 'initial' | 'all' | 'async'
• 默认值： 'async'

这表明将选择哪些 chunk 进行优化。当提供一个字符串，有效值为 all ，async 和 initial。设置为 all 可能会更强大，因为这意味着 chunk 可以在异步和非异步 chunk 之间共享。

或者，也可以提供一个函数来进行更多控制。返回值将显示是否包含该 Chunk。

还可以传递正则表达式，它是 (chunk) => regex.test(chunk.name) 的缩写。

module.exports = {
  //...
  optimization: {
    splitChunks: {
      // include all types of chunks
      chunks: 'all',
    },
  },
};

splitChunks.maxAsyncRequests#

• 类型： number
• 默认值： 30

按需加载时的最大并行请求数。

splitChunks.maxInitialRequests#

• 类型： number
• 默认值： 30

每一个入口点所允许的的最大并行请求数。

splitChunks.minSize#

• 类型： number | Record<string, number>
• 默认值： 生产环境下为 20000, 其余为 10000

生成 chunk 的最小体积（以 bytes 为单位）。

splitChunks.minChunks#

splitChunks.cacheGroups.{cacheGroup}.minChunks#

• 类型： number
• 默认值： 1

拆分前必须共享模块的最小 chunk 数。

splitChunks.hidePathInfo#

• 类型： boolean
• 默认值： options.mode 为 'production' 时默认为 true

是否隐藏路径名。

splitChunks.maxSize#

使用 maxSize（每个缓存组 optimization.splitChunks.cacheGroups[x].maxSize 全局使用 optimization.splitChunks.maxSize 或对后备缓存组 optimization.splitChunks.fallbackCacheGroup.maxSize 使用）告诉 Rspack 尝试将大于 maxSize 个字节的 chunk 分割成较小的部分。 这些较小的部分在体积上至少为 minSize（仅次于 maxSize）。 该算法是确定性的，对模块的更改只会产生局部影响。这样，在使用长期缓存时就可以使用它并且不需要记录。maxSize 只是一个提示，当模块大于 maxSize 或者拆分不符合 minSize 时可能会被违反。

当 chunk 已经有一个名称时，每个部分将获得一个从该名称派生的新名称。 根据 optimization.splitChunks.hidePathInfo 的值，它将添加一个从第一个模块名称或其哈希值派生的密钥。

maxSize 选项旨在与 HTTP/2 和长期缓存一起使用。它增加了请求数量以实现更好的缓存。它还可以用于减小文件大小，以加快二次构建速度。

splitChunks.maxAsyncSize#

• 类型： number | Record<string, number>

像 maxSize 一样，maxAsyncSize 可以为 cacheGroups（splitChunks.cacheGroups.{cacheGroup}.maxAsyncSize）或 fallback 缓存组（splitChunks.fallbackCacheGroup.maxAsyncSize ）全局应用（splitChunks.maxAsyncSize）

maxAsyncSize 和 maxSize 的区别在于 maxAsyncSize 仅会影响按需加载 chunk。

splitChunks.maxInitialSize#

• 类型： number | Record<string, number>

像 maxSize 一样，maxInitialSize 可以对 cacheGroups（splitChunks.cacheGroups.{cacheGroup}.maxInitialSize）或 fallback 缓存组（splitChunks.fallbackCacheGroup.maxInitialSize）全局应用（splitChunks.maxInitialSize）。

maxInitialSize 和 maxSize 的区别在于 maxInitialSize 仅会影响初始加载 chunks。

splitChunks.automaticNameDelimiter#

• 类型： string
• 默认值： -

默认情况下，Rspack 将使用 chunk 的来源和名称生成名称（例如 vendors-main.js）。此选项使你可以指定用于生成名称的分隔符。

splitChunks.name#

splitChunks.cacheGroups.{cacheGroup}.name#

• 类型： string | function
• 默认值： false

其中函数类型的版本要求为 >=0.4.1

每个 cacheGroup 也可以使用：splitChunks.cacheGroups.{cacheGroup}.name。

拆分 chunk 的名称。设为 false 将保持 chunk 的相同名称，因此不会不必要地更改名称。这是生产环境下构建的建议值。

如果 splitChunks.name 与 entry point 名称匹配，entry point 将被删除。

splitChunks.usedExports#

• 类型： boolean
• 默认值： 默认值为 optimization.usedExports

开启该配置后，在拆分 chunk 将根据 module 在不同 runtime 中导出的使用情况进行分组，保持在不同 runtime 中都是最优的加载体积。

举个例子，如果一次构建中有 3 个入口分别名为 foo, bar 和 baz，他们都依赖了一个相同的模块 shared，但 foo 和 bar 依赖 shared 中的导出 value1，而 baz 依赖了 shared 中的导出 value2。

import { value1 } from 'shared';
value1;

import { value1 } from 'shared';
value1;

import { value2 } from 'shared';
value2;

默认的策略中 shared 模块由于同时出现在 3 个 chunk 中，如果它满足了最小拆分体积，那么 shared 本该被抽离到一个单独 chunk 中。

但这样会导致 3 个入口都不满足最佳的加载体积，从 foo 和 bar 入口加载 shared 会多加载并不需要的导出 value2，而从 baz 入口加载 shared 会多加载并不需要的导出 value1。

当开启 splitChunks.usedExports 优化后，会分析 shared 模块分别在不同入口中用到的导出，发现在 foo 和 bar 中用到的导出和 baz 中不一样，会产生 2 个不同的 chunk，其中一个对应入口 foo 和 bar，另一个对应入口 baz。

splitChunks.cacheGroups#

缓存组可以继承和/或覆盖来自 splitChunks.* 的任何选项。但是 test、priority 和 reuseExistingChunk 只能在缓存组级别上进行配置。将它们设置为 false 以禁用任何默认缓存组。

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        default: false,
      },
    },
  },
};

splitChunks.cacheGroups.{cacheGroup}.priority#

• 类型： number
• 默认值： -20

一个模块可以属于多个缓存组。优化将优先考虑具有更高 priority（优先级）的缓存组。默认组的优先级为负，以允许自定义组获得更高的优先级（自定义组的默认值为 0）。

splitChunks.cacheGroups.{cacheGroup}.test#

• 类型： RegExp | string | function

其中函数类型的版本要求为 >=0.4.1

控制此缓存组选择的模块。省略它会选择所有模块。它可以匹配绝对模块资源路径或 chunk 名称。匹配 chunk 名称时，将选择 chunk 中的所有模块。

splitChunks.cacheGroups.{cacheGroup}.enforce#

• 类型： boolean

告诉 Rspack 忽略 splitChunks.minSize、splitChunks.minChunks、splitChunks.maxAsyncRequests 和 splitChunks.maxInitialRequests 选项，并始终为此缓存组创建 chunk。

splitChunks.cacheGroups.{cacheGroup}.idHint#

• 类型： string

设置 chunk id 的提示。 它将被添加到 chunk 的文件名中。

splitChunks.cacheGroups.{cacheGroup}.filename#

• 类型： string

仅在初始 chunk 时才允许覆盖文件名。 也可以在 output.filename 中使用所有占位符。

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        defaultVendors: {
          filename: 'vendors-[name].js',
        },
      },
    },
  },
};

splitChunks.cacheGroups.{cacheGroup}.reuseExistingChunk#

• 类型： boolean
• 默认值： false

是否重用现有的 chunk。如果经过拆分后新产生的 chunk 中包含的模块和原 chunk 中包含的模块完全一致，则原 chunk 会被复用，不会生成新的 chunk，这可能会影响 chunk 最终的文件名。举例：

由于 cacheGroup 的配置，在 chunk Foo 和 chunk Bar 中的 module B 会被拆分到一个新的 chunk 中，该 chunk 只包含 module B，这个新 chunk 和 chunk Bar 包含的 module 完全一样，因此可以直接复用 chunk Bar。

如果设置 reuseExistingChunk 为 false，那么 chunk Bar 和 chunk Foo 中的 module B 会被移到新 chunk 中，chunk Bar 由于不包含任何 module，会作为空 chunk 被删除。