在你的平台上实现 Partial Prerendering
面向平台工程师的指南,介绍如何实现 PPR 支持,从基础的源站渲染到优化的 CDN 集成。
Partial Prerendering(PPR)在单个路由中结合了静态和动态渲染。在构建时,Next.js 会为每个启用 PPR 的路由生成一个静态 HTML 外壳和一个 postponedState 数据块。在请求时,外壳会立即被提供,动态部分会被渲染并流式传输到客户端。
本页介绍平台如何在不同的复杂度级别上实现 PPR 支持。
PPR 的工作原理#
构建时#
对于每个 PPR 路由,Next.js 会生成:
- 一个静态 HTML 外壳,包含所有可以预渲染的内容,在动态内容将出现的位置带有 Suspense 回退内容。
- 一个
postponedState值:一个序列化的字符串。将其视为不透明的:直接传递,不要解析或修改它。修改postponedState会产生错误的动态渲染输出。 - 针对页面静态部分的 RSC Payload。
请求时#
当针对某个 PPR 路由的请求到达时:
- 服务器立即将静态 HTML 外壳发送到客户端。
- 服务器使用 postponed state 恢复对动态部分的渲染。
- 动态内容被流式传输到客户端,使 React 能够对延迟的 Suspense 边界进行 hydration。
客户端会立即看到静态外壳,随后动态内容在解析完成时出现。
存储 PPR 产物#
每个 PPR 路由都需要将两项产物存储在一起:
- 静态 HTML 外壳。
postponedState数据块。
这些产物必须以原子方式存储和更新。当 PPR 路由被重新验证时(通过基于时间的或按需重新验证),Next.js 会同时重新生成外壳和 postponed state。用新的外壳搭配旧的 postponed state,或反之,都会产生错误的动态内容。
在适配器中使用 requestMeta.onCacheEntryV2 来观察缓存更新,并将其传播到你的存储后端。
仅源站实现#
这是最简单的方法,适用于每个支持流式 HTTP 响应的平台。
所有请求都直接发送到 Next.js 服务器。服务器从其本地缓存中读取外壳并发送,然后渲染并流式传输动态内容。这就是 next start 的默认行为。
无需额外的基础设施。如果你的平台支持流式 HTTP 响应,它就支持 PPR。
CDN 外壳 + 源站计算#
为了获得更好的 TTFB,可以将静态 HTML 外壳缓存在 CDN 边缘。当请求到达时:
- CDN 立即提供缓存的外壳(边缘延迟)。
- CDN 向源站发送恢复请求(理想情况下与流式传输外壳并行)。
- 源站只渲染动态部分并将其流式返回。
- CDN 将外壳和动态内容拼接成单个流式响应返回给客户端。
这要求 CDN 支持一种在单个流式响应中组合缓存内容和动态内容的机制。静态外壳的 TTFB 降至边缘延迟,而动态内容仍从源站流式传输。
为了获得尽可能低的延迟,可以从边缘存储(例如在 onBuildComplete 期间填充的 KV 存储)提供外壳,而不是从 CDN 缓存提供。这是平台架构的决策,不需要对 Next.js 应用做任何更改。
恢复协议#
恢复协议告诉 Next.js 处理程序跳过外壳,只渲染动态部分。它被 CDN 到源站的架构以及单独提供外壳的基于适配器的部署所使用。
在标准的 next start 中,服务器会在一次处理中自动处理外壳和动态渲染。
CDN 到源站#
当 CDN 向独立的 Next.js 源站发出 HTTP 请求时:
- 向该路由发送带有
next-resume: 1标头的 POST 请求。 - 将
postponedState数据块作为请求体包含在内。 - 服务器将只渲染延迟的 Suspense 边界并流式传输结果。
小知识: 当 POST 请求将 Server Action 与 PPR 恢复结合时,请求体包含 postponed state,其后是 action 的请求体。
x-next-resume-state-length标头携带 postponed state 前缀的字节长度,以便处理程序将两者分开。对于纯 PPR 恢复(常见情况),整个请求体就是 postponed state,不需要此标头。
基于适配器#
当平台直接调用处理函数时:
- 调用入口点处理程序,将
req.method设置为'POST',在请求上设置next-resume: 1标头,并将postponedState作为请求体。(你也可以将requestMeta: { postponed: postponedState }作为第三个参数传给处理程序调用,这是等效的,但完全绕过了 HTTP 层。) - 处理程序只渲染延迟的 Suspense 边界,并将结果流式传输到
res。 - 无需 HTTP 往返:处理程序在进程内被调用。
在构建产物中查找 PPR 路由#
在适配器产物中,PPR 路由通过 prerenders 数组中的 renderingMode: 'PARTIALLY_STATIC' 来标识。遍历 outputs.prerenders 以查找这些条目并读取 fallback.postponedState。
pprChain.headers 包含恢复协议所需的标头:{ 'next-resume': '1' }。
有关带代码示例的详细实现,请参阅在适配器中实现 PPR。
实现清单#
- 在构建时读取 PPR 产物。 在适配器的
onBuildComplete中,识别具有renderingMode: 'PARTIALLY_STATIC'的预渲染项。将外壳 HTML 和postponedState存储在缓存中。 - 在请求时提供外壳。 对于传入 PPR 路由的请求,立即提供缓存的外壳并开始流式传输。
- 恢复动态渲染。 对于 CDN 到源站:向 Next.js 处理程序发送带有
next-resume: 1标头且以 postponed state 为请求体的 POST 请求。对于基于适配器:直接以 POST 方法调用处理程序,并在请求体中传入 postponed state(或将requestMeta: { postponed: postponedState }传给处理程序)。将响应流式返回给客户端。 - 处理缓存更新。 使用
requestMeta.onCacheEntryV2在重新验证后捕获新的外壳 + postponed state 组合,并以原子方式更新缓存。 - 支持优雅降级。 如果 postponed state 不可用或已过期,则回退到完整的服务器渲染。用户会获得完整的页面,但没有外壳优先的优化。
有关完整的适配器 API 参考和实现示例,请参阅部署适配器 API。