NNext.js 中文网 GitHub

在你的平台上实现 Partial Prerendering

面向平台工程师的指南,介绍如何实现 PPR 支持,从基础的源站渲染到优化的 CDN 集成。

Partial Prerendering(PPR)在单个路由中结合了静态和动态渲染。在构建时,Next.js 会为每个启用 PPR 的路由生成一个静态 HTML 外壳和一个 postponedState 数据块。在请求时,外壳会立即被提供,动态部分会被渲染并流式传输到客户端。

本页介绍平台如何在不同的复杂度级别上实现 PPR 支持。

PPR 的工作原理#

构建时#

对于每个 PPR 路由,Next.js 会生成:

  • 一个静态 HTML 外壳,包含所有可以预渲染的内容,在动态内容将出现的位置带有 Suspense 回退内容。
  • 一个 postponedState 值:一个序列化的字符串。将其视为不透明的:直接传递,不要解析或修改它。修改 postponedState 会产生错误的动态渲染输出。
  • 针对页面静态部分的 RSC Payload。

请求时#

当针对某个 PPR 路由的请求到达时:

  1. 服务器立即将静态 HTML 外壳发送到客户端。
  2. 服务器使用 postponed state 恢复对动态部分的渲染。
  3. 动态内容被流式传输到客户端,使 React 能够对延迟的 Suspense 边界进行 hydration。

客户端会立即看到静态外壳,随后动态内容在解析完成时出现。

存储 PPR 产物#

每个 PPR 路由都需要将两项产物存储在一起:

  1. 静态 HTML 外壳。
  2. postponedState 数据块。

这些产物必须以原子方式存储和更新。当 PPR 路由被重新验证时(通过基于时间的或按需重新验证),Next.js 会同时重新生成外壳和 postponed state。用新的外壳搭配旧的 postponed state,或反之,都会产生错误的动态内容。

在适配器中使用 requestMeta.onCacheEntryV2 来观察缓存更新,并将其传播到你的存储后端。

仅源站实现#

这是最简单的方法,适用于每个支持流式 HTTP 响应的平台。

所有请求都直接发送到 Next.js 服务器。服务器从其本地缓存中读取外壳并发送,然后渲染并流式传输动态内容。这就是 next start 的默认行为。

无需额外的基础设施。如果你的平台支持流式 HTTP 响应,它就支持 PPR。

CDN 外壳 + 源站计算#

为了获得更好的 TTFB,可以将静态 HTML 外壳缓存在 CDN 边缘。当请求到达时:

  1. CDN 立即提供缓存的外壳(边缘延迟)。
  2. CDN 向源站发送恢复请求(理想情况下与流式传输外壳并行)。
  3. 源站只渲染动态部分并将其流式返回。
  4. 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。

实现清单#

  1. 在构建时读取 PPR 产物。 在适配器的 onBuildComplete 中,识别具有 renderingMode: 'PARTIALLY_STATIC' 的预渲染项。将外壳 HTML 和 postponedState 存储在缓存中。
  2. 在请求时提供外壳。 对于传入 PPR 路由的请求,立即提供缓存的外壳并开始流式传输。
  3. 恢复动态渲染。 对于 CDN 到源站:向 Next.js 处理程序发送带有 next-resume: 1 标头且以 postponed state 为请求体的 POST 请求。对于基于适配器:直接以 POST 方法调用处理程序,并在请求体中传入 postponed state(或将 requestMeta: { postponed: postponedState } 传给处理程序)。将响应流式返回给客户端。
  4. 处理缓存更新。 使用 requestMeta.onCacheEntryV2 在重新验证后捕获新的外壳 + postponed state 组合,并以原子方式更新缓存。
  5. 支持优雅降级。 如果 postponed state 不可用或已过期,则回退到完整的服务器渲染。用户会获得完整的页面,但没有外壳优先的优化。

有关完整的适配器 API 参考和实现示例,请参阅部署适配器 API。

Next.js 中文网