NNext.js 中文网 GitHub

turbopackChunking

experimental

配置 Turbopack 在生产环境中如何将客户端 JavaScript 拆分为多个 chunk。

experimental.turbopackChunking 允许你配置 Turbopack 的生产环境 JavaScript 分块器(chunker)。这些选项可让你更改分块器对用户行为所做的假设、调整其使用的原始大小阈值,并启用实验性的组件 chunk 功能。

experimental.turbopackChunking 允许你配置 Turbopack 的生产环境 JavaScript 分块器。这些选项可让你更改分块器对用户行为所做的假设,并调整其使用的原始大小阈值。

默认情况下,Turbopack 的分块配置如下:

next.config.ts
import type { NextConfig } from 'next'

const nextConfig = {
  experimental: {
    turbopackChunking: {
      minChunkSize: 50000,
      maxChunkCountPerGroup: 40,
      maxMergeChunkSize: 200000,
      maxChunkSize: 1000000,
      minServerChunkSize: 4000,
      maxMergeServerChunkSize: 100000,
      maxServerChunkSize: 10000000,
      minComponentChunkSize: 20000,
      generateComponentChunks: false,
    },
  },
} satisfies NextConfig

export default nextConfig
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    turbopackChunking: {
      minChunkSize: 50000,
      maxChunkCountPerGroup: 40,
      maxMergeChunkSize: 200000,
      maxChunkSize: 1000000,
      minServerChunkSize: 4000,
      maxMergeServerChunkSize: 100000,
      maxServerChunkSize: 10000000,
      minComponentChunkSize: 20000,
      generateComponentChunks: false,
    },
  },
}

module.exports = nextConfig
next.config.ts
import type { NextConfig } from 'next'

const nextConfig = {
  experimental: {
    turbopackChunking: {
      minChunkSize: 50000,
      maxChunkCountPerGroup: 40,
      maxMergeChunkSize: 200000,
      maxChunkSize: 1000000,
      minServerChunkSize: 4000,
      maxMergeServerChunkSize: 100000,
      maxServerChunkSize: 10000000,
    },
  },
} satisfies NextConfig

export default nextConfig
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    turbopackChunking: {
      minChunkSize: 50000,
      maxChunkCountPerGroup: 40,
      maxMergeChunkSize: 200000,
      maxChunkSize: 1000000,
      minServerChunkSize: 4000,
      maxMergeServerChunkSize: 100000,
      maxServerChunkSize: 10000000,
    },
  },
}

module.exports = nextConfig

大小阈值#

以下选项控制 Turbopack 合并客户端 chunk 的积极程度,以及允许 chunk 增长到多大。默认情况下,大小以未压缩、未精简的代码的字节数计(约为压缩、精简后输出大小的 5 倍)。启用 minify-before-chunking 后,大小改为以未压缩的精简代码计,如下所述。

  • minChunkSize(默认 50000):Turbopack 会通过将较小的 chunk 合并为较大的 chunk,避免创建多个小于此大小的 chunk。提高此数值会产生更少、更大的 chunk。相反,降低它会产生更多、更小的 chunk。
  • maxChunkCountPerGroup(默认 40):每个 chunk 组(例如一个路由或一个动态导入)中,Turbopack 输出的 chunk 不会超过此数量。降低此数值会导致更积极的合并,并减少每页的网络请求。提高它会产生更小的 chunk,并增加导航时缓存命中的可能性。
  • maxMergeChunkSize(默认 200000):Turbopack 永远不会将大于此大小的 chunk 与其他 chunk 合并。这可以避免大 chunk 中的代码在多个大的输出 chunk 中重复出现。
  • maxChunkSize(默认 1000000):尽力估算的客户端 JavaScript chunk 大小上限。Turbopack 永远不会将 chunk 合并为大于此值的 chunk,并且会将自身大于此值的 chunk 拆分为更小的 chunk。它按标识符对模块排序,并优先在路径差异最大的地方(例如两个包之间)进行拆分,这使拆分保持确定性,并有助于避免无关的 chunk 变化。为保持在限制之内,它可能会创建小于 minChunkSize 的 chunk,或数量超过 maxChunkCountPerGroup 的 chunk。单个大于此大小的模块仍会产生更大的 chunk。该值必须至少是 minChunkSize 的 3 倍,且 maxMergeChunkSize 不得大于它。否则,Turbopack 会相应地提高 maxChunkSize 或降低 maxMergeChunkSize,并显示警告。将其设置为 0 可禁用该限制。

合并 chunk 时,所做的权衡是以牺牲导航性能为代价换取首次页面加载性能的提升。这是因为每增加一次网络请求的代价都很高,但较小的 chunk 更有可能在页面之间复用。

小知识:大小阈值取决于实验性的 experimental.turbopackMinifyBeforeChunking 选项,该选项在 canary 版本中默认启用。启用它时(且精简功能已开启),Turbopack 会在分块前精简每个模块,并改为以精简代码的字节数来衡量大小。随后,默认阈值和 requestCost(包括下面的服务端 chunk 阈值)会按比例缩减为此处所列值的 40%。特别是,默认的 maxChunkSize 变为 400000,默认的 maxServerChunkSize 变为 4000000。你显式设置的值(包括 0)会按原样使用,因此启用该选项时可能需要降低它们。

服务端 chunk#

上述大小阈值仅适用于客户端 JavaScript。服务端 JavaScript 使用单独的阈值:

  • minServerChunkSize(默认 4000):Turbopack 会通过将较小的 chunk 合并为较大的 chunk,避免创建多个小于此大小的 Node.js 服务端 chunk,除非最大 chunk 大小优先。
  • maxMergeServerChunkSize(默认 100000):Turbopack 永远不会将大于此大小的 Node.js 服务端 chunk 与其他 chunk 合并。
  • maxServerChunkSize(默认 10000000):与 maxChunkSize 类似,但适用于服务端(Node.js 和 edge)JavaScript chunk,而非客户端 chunk。对于 Node.js,它必须至少是 minServerChunkSize 的 3 倍,且 maxMergeServerChunkSize 不得大于它。否则,Turbopack 会相应地提高 maxServerChunkSize 或降低 maxMergeServerChunkSize,并显示警告。将其设置为 0 可禁用最大大小限制。

minServerChunkSize 和 maxMergeServerChunkSize 不适用于 Edge 运行时。Edge 使用 20 KB 的最小值(分块前精简时为 8 KB)和有效的 maxServerChunkSize 作为其合并上限。如果其最大值已启用但低于该最小值的 3 倍(分别为 60 KB 或 24 KB),则会在发出警告后将其提高。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    turbopackChunking: {
      minServerChunkSize: 10000,
      maxMergeServerChunkSize: 200000,
    },
  },
}

module.exports = nextConfig

组件 chunk#

生成组件 chunk 是一项实验性功能,旨在让你在不牺牲可复用性的前提下获得合并 chunk 带来的首次页面加载优势。此功能让运行时可以动态选择是将合并后的 chunk 作为单个文件加载,还是只加载它尚不具备的组件 chunk。此外,已作为合并 chunk 一部分加载的 chunk 不会被重新下载。

这避免了导航时重新下载浏览器已有的 JavaScript。

  • generateComponentChunks(默认 false):启用后,每个合并后的生产 chunk 还会同时输出其组成的组件 chunk,以便浏览器运行时可以获取单个组件 chunk。
  • minComponentChunkSize(默认 20000):小于此大小的组件 chunk 会被合并到单个组件中,而不是单独输出,以避免产生大量极小的 chunk。

启发式方法#

这些选项会改变分块器在权衡是否值得合并两个 chunk 时所做的假设。

  • clusters(RegExp 数组的数组,例如 [[/^\/dashboard/, /^\/settings/]]):经常被一起访问的路由分组,与路由 pathname 匹配。Turbopack 假定导航很可能停留在某个组内,因此更积极地合并同一组路由共享的 chunk。
  • firstPageLoadPriority(0 到 1 之间的数字):对单次页面加载时合并 chunk 的收益赋予多大权重。值越高,合并越积极。如果你没有更合适的值,可以使用网站的跳出率作为近似参考。
  • priorityRoutes(RegExp 数组):访问者经常作为首个落脚页面的路由(例如首页)。它们的客户端 bundle 会被更积极地合并,以降低单路由的请求成本,代价是导航到其他页面时会产生额外请求。
  • priorityBoost(默认 1.5):priorityRoutes 路由单次请求概率的乘数。值越高,对这些路由 bundle 的合并越激进。
  • requestCost(默认 200000):一次额外请求的预估成本,以未压缩、未精简代码的字节数计。值越大,越倾向于更少、更大的 chunk 以及更少的总体请求数。
Next.js 中文网