turbopackChunking
experimental
配置 Turbopack 在生产环境中如何将客户端和服务端 JavaScript 拆分为 chunk。
experimental.turbopackChunking 允许你配置 Turbopack 的生产环境 JavaScript 分块器(chunker)。这些选项可让你更改分块器对用户行为所做的假设、调整其使用的原始大小阈值,并启用实验性的组件 chunk 功能。
experimental.turbopackChunking 允许你配置 Turbopack 的生产环境 JavaScript 分块器。这些选项可让你更改分块器对用户行为所做的假设,并调整其使用的原始大小阈值。
默认情况下,Turbopack 的分块配置如下:
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/** @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 = nextConfigimport 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/** @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),则会在发出警告后将其提高。
/** @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 以及更少的总体请求数。