NNext.js 中文网 GitHub

在 Next.js 中使用 CDN

了解 CDN 缓存如何与 Next.js 协同工作,包括目前可用的功能、缓存的可变性,以及朝着基于路径名的缓存键方向发展的趋势。

Next.js 会设置标准的 Cache-Control 标头,CDN 可使用这些标头在边缘缓存响应。本页介绍目前可用的功能、CDN 缓存面临挑战的场景,以及消除对自定义标头依赖的发展方向。

目前可用的功能#

Cache-Control 标头#

Next.js 会根据每个路由的渲染策略设置 Cache-Control 标头:

  • 静态页面(无重新验证):s-maxage=31536000(一年)
  • ISR 页面(基于时间的重新验证):s-maxage={revalidate}, stale-while-revalidate={expire - revalidate}。默认的 expire 为一年,因此默认情况下响应标头中会包含 stale-while-revalidate。你可以使用 cacheLife 自定义此设置。
  • 动态页面(无缓存):private, no-cache, no-store, max-age=0, must-revalidate

遵循 s-maxage 和 stale-while-revalidate 的 CDN 可以在边缘缓存静态和 ISR 页面。但是,仅靠 CDN 级缓存不支持按需重新验证(revalidateTag() / revalidatePath()):这些调用会使 Next.js 服务器缓存失效,但 CDN 会继续提供其缓存副本,直到 s-maxage TTL 到期。要将按需重新验证传播到 CDN,请在重新验证调用的同时触发 CDN 清除。一种常见模式是:调用 revalidateTag()/revalidatePath() 使 Next.js 服务器缓存失效,然后为受影响的键调用 CDN 清除 API(包括 HTML 和 RSC 两种变体)。

静态资源#

从 /_next/static/ 提供的静态资源(JavaScript、CSS、图片、字体)在文件名中包含内容哈希,并具有 1 年的 max-age 和 immutable 指令:public, max-age=31536000, immutable

你可以使用 assetPrefix 从其他域名或 CDN 源站提供静态资源。

静态预取(启用 PPR 的路由)#

当路由启用了部分预渲染(Partial Prerendering)并设置了 next-router-prefetch 标头(表示静态预取)时,响应是确定性的:无论客户端的路由状态如何,它都返回相同的预渲染内容。对于这些请求,不会解析 next-router-state-tree 标头,因此它不会影响响应。

对于启用 PPR 的路由,CDN 可以在满足以下条件时缓存静态预取响应:

  1. 在缓存键中包含 _rsc 搜索参数(以区分预取变体与 HTML 响应)。
  2. 遵循 Next.js 在响应上设置的 Cache-Control 标头。

小知识: 对于未启用 PPR 的路由,在预取请求期间会读取 next-router-state-tree 标头以确定要包含哪些段,由于它传递了当前的路由状态,因此增加了缓存的 vary。当启用 Cache Components 时,段级预取已经使用基于路径名的路由(例如 /page.segments/_tree.segment.rsc),CDN 可以使用标准的基于路径名的缓存键来缓存这些响应。

CDN 缓存面临挑战的场景#

App Router 的响应可能会根据多个自定义请求标头而变化。Next.js 会在响应上设置 Vary 标头,以向 CDN 表明这一点:

  • rsc — 请求是否应返回 React Server Components(RSC)payload 而不是 HTML
  • next-router-state-tree — 客户端当前的路由状态,用于动态导航期间的定向段更新
  • next-router-prefetch — 这是否是预取请求
  • next-router-segment-prefetch — 正在被预取的特定段
  • next-url — 仅针对使用拦截路由的路由添加,携带被拦截的 URL

小知识: proxy.js(以前称为 Middleware)应在 CDN 缓存之前运行,以便它仍然是身份验证、重定向和重写的真实来源。如果你的部署将 proxy.js 放在 CDN 之后,请将缓存层配置为对依赖 proxy.js 决策的路由绕过缓存。

许多 CDN 在未进行额外配置的情况下不支持 Vary。Next.js 通过 _rsc 搜索参数解决了这一问题:它是相关请求标头值的哈希,充当缓存键,确保不同的响应变体获得不同的缓存键。这确保了即使在忽略 Vary 的 CDN 上也能获得正确的响应。

在 CDN 上处理标头#

可以安全忽略的内容#

这些标头在特定情况下可以省略,而不会导致协议错误。服务器仍会返回可解析的响应,但它可能更大,或针对性不如特定导航:

next-router-state-tree:在非预取的 RSC 请求中省略时,服务器会返回完整的 payload,而不是定向的段更新。

next-router-segment-prefetch:在预取请求中省略时,服务器会回退到更宽泛的预取 payload,而不是针对特定段的 payload。

next-url:用于拦截路由,根据来源页面改变响应。如果省略,则不支持拦截路由,因为服务器不知道要匹配哪个原始路径。当省略 next-url 时,返回的是常规导航的响应:用户看到的是目标页面,而不是被拦截的目标页面。

必须保留的内容#

必须将 rsc 标头从客户端转发到服务器。该标头告诉服务器返回 RSC payload 而不是 HTML。如果 CDN 将其剥离,当客户端路由器期望 RSC 数据时服务器却返回 HTML,这会破坏客户端导航,导致改为浏览器导航。Vary 标头和 _rsc 参数的存在正是为了防止 CDN 对 RSC 请求提供缓存的 HTML 响应(或反之)。

当存在 next-router-prefetch 时,必须同时保留预取标头和 _rsc 搜索参数。 对于预取流程,_rsc 是必需的缓存清除标识符,应视为必填项。

必须将 _rsc 搜索参数包含在缓存键中。它用于区分响应变体(HTML 与 RSC、不同的预取类型)。请确保你的 CDN 不会从缓存键中剥离查询参数,因为某些 CDN 默认会这样做。默认情况下,当 RSC 请求到达时没有正确的 _rsc 值,服务器会以 307 重定向响应,指向带有正确哈希的 URL。可以通过将 experimental.validateRSCRequestHeaders 设置为 false 来禁用此行为。CDN 应遵循此重定向。在上游计算哈希的平台可以在转发之前重写请求以包含正确的 _rsc,从而避免额外的往返。

小知识: 目前,即使在静态预取期间,next-url 也会包含在 _rsc 哈希中。这意味着在当前方案下,你不能安全地忽略它,否则可能会导致缓存未命中。下面描述的基于路径名的方向解决了这一不足。

发展方向:基于路径名的缓存键#

Next.js 团队正在努力将所有影响缓存的输入移到 URL 路径名中,从而消除对自定义标头使用 Vary 的需求,并移除 _rsc 搜索参数。这解决了上述 CDN 缓存挑战。

工作原理#

该方法扩展了 output: 'export' 和段预取目前已使用的路由方案。路径名中的文件扩展名用于标识响应类型:

  • 整页 RSC:/my/page.rsc 返回整个页面的 RSC payload
  • 段 RSC:/my/page.segments/path/to/segment.segment.rsc 返回特定段的 RSC payload

在此模型下:

  • 路径名决定缓存键。 路径名中的任何内容都会影响返回哪个响应变体。
  • 可以安全地舍弃搜索参数,而不会影响返回的响应。
  • 标准的 HTTP 缓存标头(Cache-Control、max-age 等)照常受到遵循。
  • CDN 无需支持 Vary。

CDN 可以通过使用路径名作为缓存键、忽略搜索参数并遵循标准的 Cache-Control 标头,来缓存 Next.js 响应。无需理解 Vary、检查自定义标头或编写边缘逻辑。

拦截路由的变化#

在当前方案下,next-url 会参与 _rsc 哈希的计算,因此舍弃它会导致缓存未命中。在基于路径名的方案下,拦截的可变性将编码在搜索参数(而非路径名)中:

  • 如果 CDN 保留搜索参数,则拦截可正常工作。
  • 如果 CDN 舍弃搜索参数,则不支持拦截。它会优雅降级为未拦截的页面,客户端导航不会中断。

这使得对拦截路由的支持成为 CDN 的可选能力,而不是必需条件。

当前状态#

这一方向扩展了代码库中已经运行的模式(段预取路径、output: 'export' 模式)。它目前处于积极设计中。

CDN 功能兼容性#

有关显示每个主要 CDN 上可用的基础设施原语(边缘计算、键值存储、Blob 存储、PPR 恢复)的完整表格,请参阅部署到平台。

Next.js 中文网