SplitChunksPlugin

最初，chunks（以及内部导入的模块）是通过内部 webpack 图谱中的父子关系关联的。CommonsChunkPlugin 曾被用来避免他们之间的重复依赖，但是不可能再做进一步的优化。

从 webpack v4 开始，移除了 CommonsChunkPlugin，取而代之的是 optimization.splitChunks。

默认值

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

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

webpack 将根据以下条件自动拆分 chunks：

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

当尝试满足最后两个条件时，最好使用较大的 chunks。

配置

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

optimization.splitChunks

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

webpack.config.js

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

splitChunks.automaticNameDelimiter

​string = '~'​

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

splitChunks.chunks

​string = 'async' function (chunk)​

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

请注意，它也应用于回退缓存组(splitChunks.fallbackCacheGroup.chunks).

webpack.config.js

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

或者，你也可以提供一个函数去做更多的控制。这个函数的返回值将决定是否包含每一个 chunk。

module.exports = {
  //...
  optimization: {
    splitChunks: {
      chunks(chunk) {
        // exclude `my-excluded-chunk`
        return chunk.name !== 'my-excluded-chunk';
      },
    },
  },
};

splitChunks.maxAsyncRequests

​number = 30​

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

splitChunks.maxInitialRequests

​number = 30​

入口点的最大并行请求数。

splitChunks.defaultSizeTypes

[string] = ['javascript', 'unknown']

Sets the size types which are used when a number is used for sizes.

splitChunks.minChunks

​number = 1​

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

splitChunks.hidePathInfo

​boolean​

为由 maxSize 分割的部分创建名称时，阻止公开路径信息。

splitChunks.minSize

​number = 20000 { [index: string]: number }​

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

splitChunks.minSizeReduction

​number { [index: string]: number }​

生成 chunk 所需的主 chunk（bundle）的最小体积（以字节为单位）缩减。这意味着如果分割成一个 chunk 并没有减少主 chunk（bundle）的给定字节数，它将不会被分割，即使它满足 splitChunks.minSize。

splitChunks.enforceSizeThreshold

splitChunks.cacheGroups.{cacheGroup}.enforceSizeThreshold

​number = 50000​

强制执行拆分的体积阈值和其他限制（minRemainingSize，maxAsyncRequests，maxInitialRequests）将被忽略。

splitChunks.minRemainingSize

splitChunks.cacheGroups.{cacheGroup}.minRemainingSize

​number = 0​

在 webpack 5 中引入了 splitChunks.minRemainingSize 选项，通过确保拆分后剩余的最小 chunk 体积超过限制来避免大小为零的模块。 'development' 模式 中默认为 0。对于其他情况，splitChunks.minRemainingSize 默认为 splitChunks.minSize 的值，因此除需要深度控制的极少数情况外，不需要手动指定它。

splitChunks.layer

splitChunks.cacheGroups.{cacheGroup}.layer

​RegExp​ ​string​ ​function​

按模块层将模块分配给缓存组。

splitChunks.maxSize

​number = 0​

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

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

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

splitChunks.maxAsyncSize

​number​

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

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

splitChunks.maxInitialSize

​number​

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

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

splitChunks.name

​boolean = false function (module, chunks, cacheGroupKey) => string​ ​string​

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

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

提供字符串或函数使你可以使用自定义名称。指定字符串或始终返回相同字符串的函数会将所有常见模块和 vendor 合并为一个 chunk。这可能会导致更大的初始下载量并减慢页面加载速度。

如果你选择指定一个函数，则可能会发现 chunk.name 和 chunk.hash 属性（其中 chunk 是 chunks 数组的一个元素）在选择 chunk 名时特别有用。

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

main.js

import _ from 'lodash';

console.log(_.join(['Hello', 'webpack'], ' '));

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        commons: {
          test: /[\\/]node_modules[\\/]/,
          // cacheGroupKey here is `commons` as the key of the cacheGroup
          name(module, chunks, cacheGroupKey) {
            const moduleFileName = module
              .identifier()
              .split('/')
              .reduceRight((item) => item);
            const allChunksNames = chunks.map((item) => item.name).join('~');
            return `${cacheGroupKey}-${allChunksNames}-${moduleFileName}`;
          },
          chunks: 'all',
        },
      },
    },
  },
};

使用以下 splitChunks 配置来运行 webpack 也会输出一组公用组，其下一个名称为：commons-main-lodash.js.e7519d2bb8777058fa27.js（以哈希方式作为真实世界输出示例）。

splitChunks.usedExports

splitChunks.cacheGroups{cacheGroup}.usedExports

​boolean = true​

弄清哪些 export 被模块使用，以混淆 export 名称，省略未使用的 export，并生成有效的代码。 当它为 true 时：分析每个运行时使用的出口，当它为 "global" 时：分析所有运行时的全局 export 组合）。

splitChunks.cacheGroups

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

webpack.config.js

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

splitChunks.cacheGroups.{cacheGroup}.priority

​number = -20​

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

splitChunks.cacheGroups.{cacheGroup}.reuseExistingChunk

​boolean = true​

如果当前 chunk 包含已从主 bundle 中拆分出的模块，则它将被重用，而不是生成新的模块。这可能会影响 chunk 的结果文件名。

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        defaultVendors: {
          reuseExistingChunk: true,
        },
      },
    },
  },
};

splitChunks.cacheGroups.{cacheGroup}.type

​function​ ​RegExp​ ​string​

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

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        json: {
          type: 'json',
        },
      },
    },
  },
};

splitChunks.cacheGroups.test

splitChunks.cacheGroups.{cacheGroup}.test

​function (module, { chunkGraph, moduleGraph }) => boolean​ ​RegExp​ ​string​

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

为 ​{cacheGroup}.test​ 提供一个函数：

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        svgGroup: {
          test(module) {
            // `module.resource` contains the absolute path of the file on disk.
            // Note the usage of `path.sep` instead of / or \, for cross-platform compatibility.
            const path = require('path');
            return (
              module.resource &&
              module.resource.endsWith('.svg') &&
              module.resource.includes(`${path.sep}cacheable_svgs${path.sep}`)
            );
          },
        },
        byModuleTypeGroup: {
          test(module) {
            return module.type === 'javascript/auto';
          },
        },
      },
    },
  },
};

为了查看 module and chunks 对象中可用的信息，你可以在回调函数中放入 debugger; 语句。然后 以调试模式运行 webpack 构建 检查 Chromium DevTools 中的参数。

向 ​{cacheGroup}.test​ 提供 RegExp：

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        defaultVendors: {
          // Note the usage of `[\\/]` as a path separator for cross-platform compatibility.
          test: /[\\/]node_modules[\\/]|vendor[\\/]analytics_provider|vendor[\\/]other_lib/,
        },
      },
    },
  },
};

splitChunks.cacheGroups.{cacheGroup}.filename

​string​ ​function (pathData, assetInfo) => string​

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

webpack.config.js

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

若为函数，则：

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        defaultVendors: {
          filename: (pathData) => {
            // Use pathData object for generating filename string based on your requirements
            return `${pathData.chunk.name}-bundle.js`;
          },
        },
      },
    },
  },
};

通过提供以文件名开头的路径 ​'js/vendor/bundle.js'​，可以创建文件夹结构。

webpack.config.js

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

splitChunks.cacheGroups.{cacheGroup}.enforce

​boolean = false​

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

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        defaultVendors: {
          enforce: true,
        },
      },
    },
  },
};

splitChunks.cacheGroups.{cacheGroup}.idHint

​string​

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

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        defaultVendors: {
          idHint: 'vendors',
        },
      },
    },
  },
};

Examples

Defaults: Example 1

// index.js

import('./a'); // dynamic import

// a.js
import 'react';

//...

结果： 将创建一个单独的包含 react 的 chunk。在导入调用中，此 chunk 并行加载到包含 ./a 的原始 chunk 中。

为什么：

• 条件1：chunk 包含来自 node_modules 的模块
• 条件2：react 大于 30kb
• 条件3：导入调用中的并行请求数为 2
• 条件4：在初始页面加载时不影响请求

这背后的原因是什么？react 可能不会像你的应用程序代码那样频繁地更改。通过将其移动到单独的 chunk 中，可以将该 chunk 与应用程序代码分开进行缓存（假设你使用的是 chunkhash，records，Cache-Control 或其他长期缓存方法）。

Defaults: Example 2

// entry.js

// dynamic imports
import('./a');
import('./b');

// a.js
import './helpers'; // helpers is 40kb in size

//...

// b.js
import './helpers';
import './more-helpers'; // more-helpers is also 40kb in size

//...

结果： 将创建一个单独的 chunk，其中包含 ./helpers 及其所有依赖项。在导入调用时，此 chunk 与原始 chunks 并行加载。

为什么：

• 条件1：chunk 在两个导入调用之间共享
• 条件2：helpers 大于 30kb
• 条件3：导入调用中的并行请求数为 2
• 条件4：在初始页面加载时不影响请求

将 helpers 的内容放入每个 chunk 中将导致其代码被下载两次。通过使用单独的块，这只会发生一次。我们会进行额外的请求，这可以视为一种折衷。这就是为什么最小体积为 30kb 的原因。

Split Chunks: Example 1

创建一个 commons chunk，其中包括入口（entry points）之间所有共享的代码。

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        commons: {
          name: 'commons',
          chunks: 'initial',
          minChunks: 2,
        },
      },
    },
  },
};

Split Chunks: Example 2

创建一个 vendors chunk，其中包括整个应用程序中 node_modules 的所有代码。

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        commons: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          chunks: 'all',
        },
      },
    },
  },
};

Split Chunks: Example 3

创建一个 custom vendor chunk，其中包含与 RegExp 匹配的某些 node_modules 包。

webpack.config.js

module.exports = {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/](react|react-dom)[\\/]/,
          name: 'vendor',
          chunks: 'all',
        },
      },
    },
  },
};

Further Reading

• webpack's automatic deduplication algorithm example
• webpack 4: Code Splitting, chunk graph and the splitChunks optimization