SplitChunksPlugin#

默认#

开箱即用的 SplitChunksPlugin 应该适用于大多数用户。

默认情况下，它只影响按需加载的块，因为更改初始块将影响 HTML 文件应包含的脚本标签以运行项目。

Rspack 将根据以下条件自动拆分块

• 新块可以共享，或者模块来自 node_modules 文件夹
• 新块将大于 20kb（在 min+gz 之前）
• 按需加载块时，最大并行请求数将小于或等于 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#

• 类型: 'initial' | 'all' | 'async' | RegExp | ((chunk: Chunk) => bool)
• 默认: 'async'

这指示哪些块将被选中进行优化。

当提供字符串时，有效值为 all、async 和 initial。提供 all 可能特别强大，因为它意味着即使在异步和非异步块之间也可以共享块。

或者，您可以提供一个函数来获得更多控制。返回值将指示是否包含每个块。

您也可以传递一个正则表达式，它是 (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.minChunks#

splitChunks.cacheGroups.{cacheGroup}.minChunks#

• 类型: number
• 默认: 1

模块在块之间共享的最小次数，才能拆分。

splitChunks.hidePathInfo#

• 类型: boolean
• 默认: 如果 options.mode 为 'production'，则默认为 true，否则默认为 false

在为由 maxSize 拆分的部件创建名称时，防止公开路径信息。

splitChunks.minSize#

• 类型: number | Record<string, number>
• 默认: 生产环境为 20000，其他环境为 10000

生成块的最小大小（以字节为单位）。

splitChunks.maxSize#

number | Record<string, number> = 0

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

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

maxSize 选项旨在与 HTTP/2 和长期缓存一起使用。它增加了请求计数以获得更好的缓存。它也可以用来减少文件大小，以便更快地重建。

splitChunks.maxAsyncSize#

number | Record<string, number>

与 maxSize 一样，maxAsyncSize 可以全局应用（splitChunks.maxAsyncSize）、应用于缓存组（splitChunks.cacheGroups.{cacheGroup}.maxAsyncSize），或者应用于回退缓存组（splitChunks.fallbackCacheGroup.maxAsyncSize）。

maxAsyncSize 和 maxSize 之间的区别在于 maxAsyncSize 仅影响按需加载的块。

splitChunks.maxInitialSize#

number | Record<string, number>

与 maxSize 一样，maxInitialSize 可以全局应用（splitChunks.maxInitialSize）、应用于缓存组（splitChunks.cacheGroups.{cacheGroup}.maxInitialSize），或者应用于回退缓存组（splitChunks.fallbackCacheGroup.maxInitialSize）。

maxInitialSize 和 maxSize 之间的区别在于 maxInitialSize 仅影响初始加载块。

splitChunks.automaticNameDelimiter#

• 类型: string
• 默认值: -

默认情况下，Rspack 会使用代码块的来源和名称生成名称（例如 vendors-main.js）。

此选项允许您指定用于生成名称的分隔符。

splitChunks.name#

splitChunks.cacheGroups.{cacheGroup}.name#

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

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

每个缓存组也可用：splitChunks.cacheGroups.{cacheGroup}.name。

拆分代码块的名称。提供 false 将保留代码块的相同名称，因此它不会不必要地更改名称。对于生产构建，这是推荐的值。

提供字符串允许您使用自定义名称。指定字符串将合并所有公共模块和供应商到单个代码块中。这可能导致更大的初始下载量并减慢页面加载速度。

如果 splitChunks.name 与 入口点 名称匹配，则入口点将被删除。

splitChunks.usedExports#

• 类型: boolean
• 默认值: optimization.usedExports 的值

启用此配置后，代码块的拆分将根据模块导出在不同运行时中的使用情况进行分组，确保每个运行时具有最佳加载大小。

例如，如果存在三个名为 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 个代码块中。如果它满足 拆分的 minSize，那么 shared 模块应该被提取到一个单独的代码块中。

但是，这将导致三个入口点中的任何一个都没有最佳的加载大小。从 foo 和 bar 入口点加载 shared 模块将不必要地加载导出 value2，而从 baz 入口点加载将不必要地加载导出 value1。

当启用 splitChunks.usedExports 优化时，它会分析哪些 shared 模块的导出在不同的入口点中使用。它发现 foo 和 bar 中使用的导出与 baz 中使用的导出不同，从而导致创建两个不同的代码块，一个对应于入口点 foo 和 bar，另一个对应于入口点 baz。

splitChunks.defaultSizeTypes#

• 类型: string[]

设置当数字用于大小时使用的尺寸类型。

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。

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

splitChunks.cacheGroups.{cacheGroup}.enforce#

• 类型: boolean

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

splitChunks.cacheGroups.{cacheGroup}.idHint#

• 类型: string

设置代码块 ID 的提示。它将添加到代码块的文件名中。

splitChunks.cacheGroups.{cacheGroup}.filename#

• 类型: string

允许仅当它是初始代码块时覆盖文件名。output.filename 中可用的所有占位符也可在此处使用。

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

splitChunks.cacheGroups.{cacheGroup}.reuseExistingChunk#

• 类型: boolean
• 默认值 false

是否在可能的情况下重用现有的代码块。如果是，拆分后，新创建的代码块包含与原始代码块中的模块完全相同的模块，原始代码块将被重用，并且不会生成新的代码块，这可能会影响代码块的最终文件名。例如

在代码块 Foo 和 Bar 中，由于缓存组的配置，模块 B 将被拆分到一个只包含模块 B 的新代码块中。这个新代码块在它包含的模块方面与代码块 Bar 相同，因此代码块 Bar 可以直接重用。

如果 reuseExistingChunk 的设置设置为 false，那么代码块 Bar 和 Foo 中的模块 B 将被移动到一个新的代码块中，而代码块 Bar 由于不再包含任何模块，将被删除为空代码块。

splitChunks.cacheGroups.{cacheGroup}.type#

• 类型: string | RegExp

允许通过模块类型将模块分配给缓存组。