Partial Prerendering

注意： 部分预渲染是一项实验性功能，仅在 canary 版本中可用，且可能会发生变化。它尚未准备好用于生产环境。

部分预渲染（PPR）使你能够在同一路由中结合静态和动态组件。

在构建过程中，Next.js 会尽可能多地预渲染路由。如果检测到动态代码，比如从传入请求中读取数据，你可以用 React Suspense 边界包装相关组件。Suspense 边界的 fallback 将被包含在预渲染的 HTML 中。

🎥 观看： 为什么要用 PPR 以及它是如何工作的 → YouTube（10 分钟）。

背景

PPR 使你的 Next.js 服务器能够立即发送预渲染内容。

为了防止客户端到服务器的瀑布效应，动态组件在提供初始预渲染的同时开始从服务器并行流式传输。这确保动态组件可以在浏览器加载客户端 JavaScript 之前开始渲染。

为了避免为每个动态组件创建多个 HTTP 请求，PPR 能够将静态预渲染和动态组件组合到单个 HTTP 请求中。这确保每个动态组件不需要多次网络往返。

使用部分预渲染

增量采用（版本 15 Canary 版本）

在 Next.js 15 canary 版本中，PPR 作为一项实验性功能可用。它在稳定版本中尚不可用。安装方法：

npm install next@canary

你可以通过在 next.config.js 中将 ppr 选项设置为 incremental，并在文件顶部导出 experimental_ppr 路由配置选项，在布局和页面中逐步采用部分预渲染：

next.config.ts

TypeScript

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    ppr: 'incremental',
  },
}
 
export default nextConfig

app/page.tsx

TypeScript

import { Suspense } from 'react'
import { StaticComponent, DynamicComponent, Fallback } from '@/app/ui'
 
export const experimental_ppr = true
 
export default function Page() {
  return (
    <>
      <StaticComponent />
      <Suspense fallback={<Fallback />}>
        <DynamicComponent />
      </Suspense>
    </>
  )
}

值得注意的是：

没有 experimental_ppr 的路由将默认为 false，不会使用 PPR 进行预渲染。你需要为每个路由显式选择加入 PPR。

experimental_ppr 将应用于路由段的所有子项，包括嵌套布局和页面。你不必将它添加到每个文件中，只需添加到路由的顶部段。

要为子段禁用 PPR，你可以在子段中将 experimental_ppr 设置为 false。

动态组件

在 next build 期间为你的路由创建预渲染时，Next.js 要求用 React Suspense 包装动态 API。然后 fallback 会被包含在预渲染中。

例如，使用 cookies 或 headers 等函数：

app/user.tsx

TypeScript

import { cookies } from 'next/headers'
 
export async function User() {
  const session = (await cookies()).get('session')?.value
  return '...'
}

该组件需要检查传入请求以读取 cookies。要将其与 PPR 一起使用，你应该用 Suspense 包装该组件：

app/page.tsx

TypeScript

import { Suspense } from 'react'
import { User, AvatarSkeleton } from './user'
 
export const experimental_ppr = true
 
export default function Page() {
  return (
    <section>
      <h1>This will be prerendered</h1>
      <Suspense fallback={<AvatarSkeleton />}>
        <User />
      </Suspense>
    </section>
  )
}

组件只有在访问值时才会选择动态渲染。

例如，如果你从 page 中读取 searchParams，你可以将此值作为 prop 转发给另一个组件：

app/page.tsx

TypeScript

import { Table } from './table'
 
export default function Page({
  searchParams,
}: {
  searchParams: Promise<{ sort: string }>
}) {
  return (
    <section>
      <h1>This will be prerendered</h1>
      <Table searchParams={searchParams} />
    </section>
  )
}

在表格组件内部，访问 searchParams 中的值将使组件动态运行：

app/table.tsx

TypeScript

export async function Table({
  searchParams,
}: {
  searchParams: Promise<{ sort: string }>
}) {
  const sort = (await searchParams).sort === 'true'
  return '...'
}