cssChunking
experimental
使用 cssChunking 选项控制 Next.js 应用中 CSS 文件的分块方式。
CSS Chunking 是一种通过将 CSS 文件拆分并重新排序为多个块来提升 Web 应用性能的策略。它使路由只加载接近其实际所需的 CSS,而不是一次性加载应用的全部 CSS。
你可以使用 next.config.js 文件中的 experimental.cssChunking 选项来控制 CSS 文件的分块方式:
import type { NextConfig } from 'next'
const nextConfig = {
experimental: {
cssChunking: true, // 默认
},
} satisfies NextConfig
export default nextConfig/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
cssChunking: true, // 默认
},
}
module.exports = nextConfig选项#
true(默认)(webpack 和 Turbopack):Next.js 会尽可能合并 CSS 文件,根据导入顺序确定文件之间的显式和隐式依赖关系,从而减少块的数量,进而减少请求数量。false(仅 webpack):Next.js 不会尝试合并或重新排序你的 CSS 文件。'strict'(仅 webpack):Next.js 会按照 CSS 文件被导入的正确顺序加载它们,这可能导致更多的块和请求。'graph'(仅 Turbopack):Next.js 使用基于成本的图算法跨路由对 CSS 进行分组,平衡每个路由下载的字节数与其发出的请求数。
选择策略#
对于大多数应用,无论使用哪种打包器,默认值(true)都是正确的选择:它会合并 CSS 以减少请求数量。只有出于特定原因才应改用其他策略。
在 Turbopack 中,这个原因通常是性能。切换到 graph 可调整 CSS 在路由之间的共享方式,减少路由下载的未使用 CSS,但代价是更多请求(请参阅平衡请求与分组)。
在 webpack 中,这个原因通常是正确性。如果遇到意外的 CSS 行为,请切换到 'strict'。例如,如果你在不同的文件中以不同的 import 顺序(a 在 b 之前,或 b 在 a 之前)导入 a.css 和 b.css,true 会以任意顺序合并它们,并假设它们之间没有依赖关系;如果 b.css 依赖于 a.css,'strict' 会阻止合并,并按导入顺序加载它们,代价是更多的块和请求。使用 false 可完全禁用合并。
调试路由实际使用的内容#
虽然有一些未使用的 CSS 是可以接受的,而且大多数应用无需做任何更改,但检查阻塞渲染的 CSS 仍然值得。Lighthouse 会将此标记为一个 Reduce unused CSS(减少未使用的 CSS)优化机会并给出预计节省量,Chrome DevTools 则在其 Coverage 面板中按样式表显示该情况,其中使用条形图以绿色显示每个样式表已应用的 CSS,以灰色显示未使用的 CSS。
阅读报告时,请注意那些仅在交互时生效的样式,例如 :hover、:focus,或由 JavaScript 为菜单和弹窗切换的 class,因为在你触发它们之前,Coverage 会将它们计为未使用。
这些未使用 CSS 的来源有两种。要么是你的路由导入的样式表中存在死代码 CSS,你可以通过在源码中删除未使用的规则,或将它们移到只有使用它们的路由才导入的样式表中来修复(CSS Modules 通过将样式限定于导入它们的组件,使这种做法变得自然)。
要么是打包器将另一个样式表合并到了你的路由加载的共享块中。这由你的分块策略决定。在 Turbopack 中,graph 模式可让你精细调整 CSS 合并的激进程度。
平衡请求与分组#
graph 策略将 CSS 分组到共享块中以减少请求。使用字符串形式启用它,这会采用默认调优:
import type { NextConfig } from 'next'
const nextConfig = {
experimental: {
cssChunking: 'graph',
},
} satisfies NextConfig
export default nextConfig/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
cssChunking: 'graph',
},
}
module.exports = nextConfig要调整这种平衡,请改为传入一个对象。requestCost 和 weightDistribution 都是可选的,因此只包含你想更改的那一项:
import type { NextConfig } from 'next'
const nextConfig = {
experimental: {
cssChunking: {
type: 'graph',
requestCost: 100000,
weightDistribution: 0.1,
},
},
} satisfies NextConfig
export default nextConfig/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
cssChunking: {
type: 'graph',
requestCost: 100000,
weightDistribution: 0.1,
},
},
}
module.exports = nextConfigrequestCost(默认20000):每次额外 CSS 请求的预估成本,以字节为单位。值越大,越倾向于更少、更大的共享块,总体上请求也越少。weightDistribution(默认0.1):控制共享块的成本如何在加载它的各路由之间分配,权重取决于每个路由导入的 CSS 量。0表示对所有路由一视同仁;值越大,导入 CSS 较少的路由权重越高,因此算法会优先考虑 CSS 较少的路由,前提是假设在大型路由上额外的 CSS 不那么明显。
graph 如何决定合并内容#
将 CSS 合并到共享块中是默认值(true)已经在做的事;graph 只是让你可以控制它在合并与拆分之间如何取舍。
以两个共享一个样式表的路由为例:
/a → [shared.css, only-a.css]
/b → [shared.css]这里,/b 从不导入 only-a.css,因此需要做一个决定:将 only-a.css 保留在共享块中,还是让它独占一个块。
保持合并可让 /a 通过一次请求加载其全部 CSS。代价是同样加载该共享块的 /b 现在也会下载 only-a.css,尽管它从未导入过该文件。
将其拆分出来可以让 /b 省下这些字节,但 /a 现在必须发出两次请求。默认值通过固定的启发式方法在这两者之间做出选择。
requestCost 选项就是 graph 为这种权衡定价的方式:多少未导入的 CSS 相当于一次额外请求。只要 only-a.css 远低于 requestCost,它就会保持合并;一旦它增长到足以超过该请求的代价,就会被拆分出来。
决定因素是一次合并会强加给路由的未导入 CSS 的大小,这远比你加入的共享块本身的大小更重要。默认 requestCost 约为 20 KB,因此 only-a.css 必须超过大致该大小才会获得自己的块,所以小型样式表会保持合并。
<details> <summary>Graph 算法概览</summary>
从高层次看,该算法处理的是单个 CSS 文件。它从每个路由导入的 CSS 的有序列表开始:
/dashboard → [reset.css, theme.css, layout.css, dashboard.css]
/settings → [reset.css, theme.css, layout.css, settings.css]
/login → [reset.css, login.css]基于这些信息,它构建一个加权图:两个 CSS 文件被越多路由以相同顺序一起导入,它们之间的边就越重。然后它将该图展平为一条直线,使经常成对出现的文件保持相邻,接着放置 切分点 将这条线划分为多个块,例如:
reset theme layout │ dashboard │ settings │ login
└──── chunk 1 ────┘ chunk 2 chunk 3 chunk 4路由会加载包含其导入文件的所有块,因此 /dashboard 加载块 1 和块 2,而 /login 加载块 1 和块 4。
算法会选择块的分裂位置,以最小化所有路由的总下载成本,平衡字节数和请求数。它优化的是总成本,而不是每个路由各自的成本,因此当某路由携带一些它从未导入的 CSS 能降低总体成本时,就会出现这种情况。两个选项控制这种权衡:
requestCost:reset.css、theme.css和layout.css共用一个块,因此需要它们的路由只需发出一次请求,而不是三次。requestCost是以字节计的请求价格:提高它,算法就会更多地进行类似合并,以更大的下载量换取更少的请求;将其降低到接近0,算法就会拆分块,使路由下载的内容更接近其实际导入的内容,但请求数会更多。weightDistribution:/login只需要块 1 中的reset.css,但由于它们共享该块,它也会下载theme.css和layout.css。此选项决定算法在多大程度上在意这一点。为0时,/login和/dashboard权重相同,因此算法允许额外内容搭便车;提高它,像/login这样导入 CSS 很少的路由权重更高,因此算法会努力避免让它们下载从未导入的 CSS,代价是总体请求数增加。
</details>