NNext.js 中文网 GitHub

Next.js 中的重新验证是如何工作的

深入了解 Next.js 如何重新验证缓存内容,包括标签系统、缓存一致性和多实例协调。

缓存页面介绍了如何使用 use cache、cacheTag 和 cacheLife。本页面向需要理解该系统以实现自定义缓存处理器或调试重新验证行为的平台工程师和高级用户,解释重新验证在内部是如何工作的。

重新验证模型#

Next.js 中的大多数路由都可以按需重新验证。这包括 App Router 路由以及产生 ISR/预渲染缓存条目的 Pages Router 路由。自动静态优化(纯静态输出)的 Pages Router 路由不能按需重新验证。无需重新部署即可更新缓存内容的能力是 Next.js 渲染模型的核心部分。

重新验证有两种类型:

  • 基于时间的重新验证使用 stale-while-revalidate(先陈旧后重新验证)模式。缓存内容会立即提供,当内容的存在时间超过 cacheLife 或 revalidate 持续时间时,会触发后台重新生成。在新内容准备好之前,旧内容会继续被提供。
  • 按需重新验证通过调用 revalidateTag() 或 revalidatePath() 显式地使缓存内容失效。对该内容的下一次请求会触发一次全新的渲染。

小知识: Pages Router 的按需 ISR API(例如 res.revalidate() 和 x-prerender-revalidate 流程)仍然受支持,并使用服务端缓存处理器(cacheHandler,单数形式)。cacheHandlers 选项(复数形式)用于 'use cache' 指令。

哪些内容会被重新验证#

当路由被重新验证时,Next.js 会从同一个 React 组件树重新生成 HTML 响应和 RSC Payload(React Server Components payload)两者。这两个产物会一起存储在同一个缓存条目中。

这种一致性很重要,因为 RSC Payload 用于客户端导航。浏览器导航和客户端导航应当持有相同的内容。

如果两者不同步会发生什么#

如果平台的缓存将一次渲染的 HTML 和另一次渲染的 RSC Payload 混合提供,用户在客户端导航期间可能会看到过期或不匹配的内容。主要的缓解措施是:使用相同的 TTL 和失效策略将 HTML 与 RSC 响应一起缓存,并遵循 Next.js 设置的 Vary 标头。有关详情,请参阅CDN 缓存。

另一个相关但独立的问题是跨部署偏差(cross-deployment skew):在滚动部署期间,使用部署 A 构建的客户端可能会收到来自运行部署 B 的服务器的响应。deploymentId 可以缓解这一问题:当客户端检测到与服务器端不同的部署 ID 时,会触发一次硬导航以获取一致的内容。

标签系统架构#

Next.js 使用基于标签的系统来跟踪哪些缓存内容需要失效。标签有两种类型:

显式标签#

显式标签由开发者在 use cache 函数中使用 cacheTag() 设置,或在 fetch 调用中通过 next: { tags: [...] } 设置。当调用 revalidateTag('my-tag', 'max') 时,所有带有该标签的缓存条目都会失效。

软标签#

软标签由 Next.js 根据路由路径自动生成,以 _N_T_ 为前缀。例如,路由 /blog/hello 会生成 _N_T_/layout、_N_T_/blog/layout、_N_T_/blog/hello/layout 和 _N_T_/blog/hello 等软标签。路径中的每个段都会获得一个 layout 标签,此外还有叶子路由本身的标签。

软标签使 revalidatePath() 能够通过同一套基于标签的系统工作。当调用 revalidatePath('/blog/hello') 时,它会使与该路径的叶子路由标签及其祖先 layout 软标签(例如 _N_T_/layout、_N_T_/blog/layout、_N_T_/blog/hello/layout 和 _N_T_/blog/hello)相关联的缓存条目失效。

在缓存处理器 API 中,软标签会通过 softTags 参数传递给 get() 方法。你的处理器应检查是否有任何软标签在缓存条目的时间戳之后失效。getExpiration() 方法返回所有提供标签中最近一次的重新验证时间戳;如果没有任何标签被重新验证,则返回 0。它也可以返回 Infinity,以表示应将软标签传递给 get() 并在那里检查过期。如果返回的时间戳比缓存条目自身的时间戳更新,你的处理器应将条目视为陈旧。完整的语义请参阅缓存处理器 API 参考。

多实例注意事项#

在负载均衡器后面运行多个 Next.js 实例时,重新验证事件默认是本地的。在实例 A 上调用 revalidateTag() 只会使该实例上的缓存失效。其他实例会继续提供陈旧内容,直到它们获知失效事件。

缓存处理器 API 提供了两个用于分布式协调的钩子:

  • updateTags() 在调用 revalidateTag() 时被调用。你的处理器应将失效事件写入共享存储(例如 Redis 或数据库),以便其他实例能够发现它。
  • refreshTags() 会定期被调用,但总是在开始新请求之前调用。你的处理器应检查共享存储中最近的失效事件,并相应地更新本地标签状态。

有关实现细节和 Redis 示例,请参阅自定义缓存处理器。

平台的实现模式#

单实例#

默认的文件系统缓存会自动处理一致性。缓存写入在本地文件系统上是原子操作,标签状态保存在内存中。无需额外配置。

带共享缓存的多实例#

如果没有协调,每个实例都会独立地提供服务并仅使用其本地缓存处理重新验证。不同的用户可能会看到不同的内容,这取决于哪个实例为他们的请求提供服务;而按需重新验证只会在收到调用的那个实例上生效。

要缩短这个时间窗口并确保重新验证能在各实例间传播:

  1. 将标签失效时间戳存储在共享服务中(Redis、DynamoDB 或简单的 HTTP API)。
  2. 实现 updateTags() 以写入共享服务。
  3. 实现 refreshTags() 以从共享服务读取。你的处理器必须在 refreshTags() 中捕获错误:如果它抛出异常,该异常会作为请求失败向上传播。捕获错误可以让请求使用最后一次已知的本地标签状态继续执行,在连接恢复之前可能会提供陈旧内容。
  4. 将缓存条目(HTML + RSC Payload)存储在共享存储中。原子写入可以进一步缩小不匹配的时间窗口,但并非正确性的必要条件。

CDN 集成#

如果 CDN 缓存了 Next.js 的响应,它应遵循 Next.js 设置的 Vary 标头和 Cache-Control 指令。不要使用不同的 TTL 分别缓存 HTML 和 RSC Payload 响应。有关详情,请参阅CDN 缓存。

优雅降级#

重新验证系统优先保证可用性,而非严格的一致性。即使无法完全满足基础设施的保证,内容也始终会被提供:

  • 缓存写入失败:由于写入是异步的,响应仍会提供给用户。缓存条目会丢失,下一次请求会触发一次全新的渲染。
  • 缓存读取失败:你的处理器应捕获内部错误并返回 undefined(缓存未命中信号)。随后该路由会重新进行服务端渲染。抛出的错误不会被视为缓存未命中;它会作为渲染错误向上传播,因此务必返回 undefined 以表示未命中。
  • HTML/RSC 缓存不一致:如果 CDN 使用不同的 TTL 或失效时机缓存 HTML 和 RSC 响应,用户在客户端导航期间可能会看到不匹配的内容。将它们一起缓存并遵循 Vary 标头可以避免这种情况。
  • 跨部署偏差:在滚动部署期间,配置 deploymentId,以便构建 ID 发生变化时触发硬导航来获取一致的内容。

缓存失败只会导致性能下降(陈旧内容、额外渲染),而不会导致应用程序损坏。

Next.js 中文网