NNext.js 中文网 GitHub

运行时集成

了解构建时适配器与运行时缓存接口如何协同工作。

Deployment Adapter API 是一个构建时接口。它告诉你的平台构建了什么以及如何路由请求。运行时行为(请求处理、流式传输、缓存)由 Next.js 服务器本身以及缓存接口 cacheHandler 和 cacheHandlers 处理。

适配器和缓存接口共同构成完整的平台集成界面:

  • 适配器(构建时):处理构建输出、配置路由并设置特定于平台的基础设施。
  • 缓存接口(运行时):cacheHandler 管理 ISR/服务端缓存存储以及跨实例的重新验证;cacheHandlers 配置 'use cache' 指令的后端和标签协调。

Handler 上下文#

调用入口点时,适配器会将一个 ctx 对象传递给 Next.js handler。关键字段包括:

  • ctx.waitUntil:一个接受 promise 的函数。使用它可以让 serverless 函数在响应发送后保持运行,从而使缓存重新验证等后台工作得以完成。
  • requestMeta.onCacheEntryV2(通过 addRequestMeta 设置):当缓存条目生成或被查找时触发的回调。使用它可以观察所有缓存操作(而不仅是 PPR),并将缓存更新传播到平台的存储后端。此回调会在处理该请求的实例上触发。对于多实例部署,你的适配器应将更新传播到共享存储。有关协调模式,请参阅重新验证的工作原理。

PPR 链请求头#

在 prerenders 输出类型中,pprChain.headers 包含恢复协议(resume protocol)所需的请求头。具体来说,它包含 { 'next-resume': '1' }。

当你的适配器检测到一条启用了 PPR 且具有缓存静态 shell 的路由时:

  1. 在传给 Next.js handler 的内部请求上设置 pprChain.headers。
  2. 以 POST 方式发送请求,并将 postponedState 作为请求体。
  3. handler 将只渲染延迟的 Suspense 边界并流式传输结果。

小知识: 在标准的 next start 中,服务器会自动在一次处理中同时处理 shell 和动态渲染。恢复协议适用于基于适配器的部署以及希望单独提供 shell 的 CDN 到源站架构。有关完整的实现背景,请参阅 PPR 平台指南。

Next.js 中文网