运行时集成
了解构建时适配器与运行时缓存接口如何协同工作。
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 的路由时:
- 在传给 Next.js handler 的内部请求上设置
pprChain.headers。 - 以 POST 方式发送请求,并将
postponedState作为请求体。 - handler 将只渲染延迟的 Suspense 边界并流式传输结果。
小知识: 在标准的
next start中,服务器会自动在一次处理中同时处理 shell 和动态渲染。恢复协议适用于基于适配器的部署以及希望单独提供 shell 的 CDN 到源站架构。有关完整的实现背景,请参阅 PPR 平台指南。