在 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 可以在满足以下条件时缓存静态预取响应:
- 在缓存键中包含
_rsc搜索参数(以区分预取变体与 HTML 响应)。 - 遵循 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 而不是 HTMLnext-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 恢复)的完整表格,请参阅部署到平台。