NNext.js 中文网 GitHub

cssChunking

experimental

使用 cssChunking 选项控制 Next.js 应用中 CSS 文件的分块方式。

CSS Chunking 是一种通过将 CSS 文件拆分并重新排序为多个块来提升 Web 应用性能的策略。它使路由只加载接近其实际所需的 CSS,而不是一次性加载应用的全部 CSS。

你可以使用 next.config.js 文件中的 experimental.cssChunking 选项来控制 CSS 文件的分块方式:

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

const nextConfig = {
  experimental: {
    cssChunking: true, // 默认
  },
} satisfies NextConfig

export default nextConfig
next.config.js
/** @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 分组到共享块中以减少请求。使用字符串形式启用它,这会采用默认调优:

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

const nextConfig = {
  experimental: {
    cssChunking: 'graph',
  },
} satisfies NextConfig

export default nextConfig
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    cssChunking: 'graph',
  },
}

module.exports = nextConfig

要调整这种平衡,请改为传入一个对象。requestCost 和 weightDistribution 都是可选的,因此只包含你想更改的那一项:

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

const nextConfig = {
  experimental: {
    cssChunking: {
      type: 'graph',
      requestCost: 100000,
      weightDistribution: 0.1,
    },
  },
} satisfies NextConfig

export default nextConfig
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    cssChunking: {
      type: 'graph',
      requestCost: 100000,
      weightDistribution: 0.1,
    },
  },
}

module.exports = nextConfig
  • requestCost(默认 20000):每次额外 CSS 请求的预估成本,以字节为单位。值越大,越倾向于更少、更大的共享块,总体上请求也越少。
  • weightDistribution(默认 0.1):控制共享块的成本如何在加载它的各路由之间分配,权重取决于每个路由导入的 CSS 量。0 表示对所有路由一视同仁;值越大,导入 CSS 较少的路由权重越高,因此算法会优先考虑 CSS 较少的路由,前提是假设在大型路由上额外的 CSS 不那么明显。

graph 如何决定合并内容#

将 CSS 合并到共享块中是默认值(true)已经在做的事;graph 只是让你可以控制它在合并与拆分之间如何取舍。

以两个共享一个样式表的路由为例:

txt
/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 的有序列表开始:

txt
/dashboard  → [reset.css, theme.css, layout.css, dashboard.css]
/settings   → [reset.css, theme.css, layout.css, settings.css]
/login      → [reset.css, login.css]

基于这些信息,它构建一个加权图:两个 CSS 文件被越多路由以相同顺序一起导入,它们之间的边就越重。然后它将该图展平为一条直线,使经常成对出现的文件保持相邻,接着放置 切分点 将这条线划分为多个块,例如:

txt
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>

Next.js 中文网