NNext.js 中文网 GitHub

结合 Cache Components 的增量静态再生成

了解如何预渲染一部分动态路由、为其余路由提供 App Shell,并在首次访问后对其进行升级。

增量静态再生成(Incremental Static Regeneration,ISR)结合 cacheComponents 和 Partial Prefetching,让每个路由都能实现即时的首次访问,即使是那些未包含在构建中的 URL。

在构建期间,部分预渲染将每次渲染分为两部分:

  • App Shell:页面中不依赖 URL 数据的通用、可复用部分
  • 其余可静态渲染的内容:针对你在 generateStaticParams 中列出的 URL 的特定参数预渲染

对于参数包含在 generateStaticParams 中的 URL 访问,Next.js 会从缓存中提供完全预渲染的页面。对于参数未包含在其中的 URL 访问,Next.js 会立即提供 App Shell,然后在后台使用现已已知的参数对其进行升级。对该 URL 的后续访问会直接从缓存中获得升级后的结果,完全跳过 App Shell。

如果你在 Pages Router 中使用过 ISR 或 fallback: true,那么这就是 Cache Components 中等价的功能。

同时启用 cacheComponents 和 Partial Prefetching。

Cache Components 会预渲染一个可包含回退 UI 的静态外壳。对于 generateStaticParams 未返回的路径,Next.js 可以按需渲染该路径,并将完成的结果存储在 ISR 缓存中。

Partial Prefetching 决定是否在 URL 特定的渲染完成之前提供回退内容:

  • 启用 Partial Prefetching 时: 你可以在 <Suspense> 内部等待 params。Next.js 可以立即为未列出的路径提供回退内容,渲染 URL 特定的内容,并将完成的结果存储在 ISR 缓存中。
  • 未启用 Partial Prefetching 时: 对未列出路径的第一个请求必须等待 URL 特定的渲染完成。请在任何 <Suspense> 边界之外等待 params(包括由 loading.tsx 创建的边界),以便 Next.js 为该 URL 创建 ISR 条目。

小知识: 未启用 Partial Prefetching 时,在 <Suspense> 内部等待 params 会导致 Next.js 持续提供共享的回退内容,而不是创建 URL 特定的 ISR 条目。路由获取的数据仍然可以独立缓存。

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
}

export default nextConfig

示例#

我们将使用 Recipe API 构建一个包含分类布局和产品详情页的产品目录。你可以在这里找到本示例使用的资源:

准备你的路由#

使用 generateStaticParams 定义要预渲染的参数值。在渲染这些路由时,参数值在构建时就是已知的。预渲染过程会构建静态外壳,直到遇到 Request-time API 或未缓存的数据。有关更多详情,请参阅预渲染。

分类布局预渲染两个分类:

app/[category]/layout.tsx
import Link from 'next/link'
import { Suspense } from 'react'
import { getCategory, getTopCategories } from '../lib/data'

export async function generateStaticParams() {
  const categories = await getTopCategories()
  return categories.map((c) => ({ category: c.slug }))
}

async function CategoryHeader({
  params,
}: Pick<LayoutProps<'/[category]'>, 'params'>) {
  const { category } = await params
  const data = await getCategory(category)

  return (
    <div>
      <Link href="/">&larr; All categories</Link>
      <h1>{data?.name ?? 'Category'}</h1>
      {data?.description && <p>{data.description}</p>}
    </div>
  )
}

export default function CategoryLayout(props: LayoutProps<'/[category]'>) {
  return (
    <div>
      <Suspense fallback={<div>Loading...</div>}>
        <CategoryHeader params={props.params} />
      </Suspense>
      {props.children}
    </div>
  )
}

注意,CategoryLayout 本身并不 await props.params。相反,它将 params 的 Promise 传递给 <Suspense> 内部的 CategoryHeader。await 发生在边界内部,因此对于未知分类,Next.js 仍能生成 App Shell。即使是 generateStaticParams 覆盖的分类,也要将读取操作保留在边界内部。静态已知的参数仍然属于某一个 URL,因此在 Suspense 边界之上等待它会将此布局的 App Shell 绑定到该 URL。有关以这种方式组织路由,请参阅即时导航。

产品页面为每个分类预渲染一个产品。generateStaticParams 接收父级的 category 参数:

app/[category]/[product]/page.tsx
import { Suspense } from 'react'
import Link from 'next/link'
import { getProduct, getPopularProducts } from '../../lib/data'

export async function generateStaticParams({
  params,
}: {
  params: { category: string }
}) {
  const products = await getPopularProducts(params.category)
  return products.map((p) => ({ product: p.slug }))
}

async function ProductDetails(props: PageProps<'/[category]/[product]'>) {
  const { category, product } = await props.params
  const data = await getProduct(category, product)

  if (!data) {
    return <p>Product not found.</p>
  }

  return (
    <>
      <Link href={`/${category}`} prefetch={true}>
        &larr; Back to products
      </Link>
      <h2>{data.name}</h2>
      <p>${data.price}</p>
      <p>{data.description}</p>
    </>
  )
}

export default function ProductPage(props: PageProps<'/[category]/[product]'>) {
  return (
    <div>
      <Suspense fallback={<div>Loading product...</div>}>
        <ProductDetails {...props} />
      </Suspense>
    </div>
  )
}

小知识: 你也可以使用 loading.tsx 文件来代替 JSX 中的 <Suspense>。loading.tsx 将边界放在路由段的边缘,而内联的 <Suspense> 让你可以将它放在组件树中的任意位置。

数据辅助函数在模块级别使用 'use cache',因此所有导出函数都会被缓存。这使得它们的结果能够被包含在静态外壳中:

app/lib/data.ts
'use cache'

const API = 'https://next-recipe-api.vercel.dev'

export async function getCategory(slug: string) {
  const res = await fetch(`${API}/categories/${slug}`)
  if (!res.ok) return null
  return res.json()
}

export async function getProduct(category: string, slug: string) {
  const res = await fetch(`${API}/products/${category}/${slug}`)
  if (!res.ok) return null
  return res.json()
}

export async function getTopCategories() {
  const res = await fetch(`${API}/categories`)
  const categories = await res.json()
  return categories.slice(0, 2)
}

export async function getPopularProducts(category: string) {
  const res = await fetch(`${API}/products?category=${category}`)
  const products = await res.json()
  return products.slice(0, 1)
}

如果组件访问了 Request-time API(例如 cookies() 或 headers()),请将其包裹在 <Suspense> 中。在预渲染期间,Next.js 会将最近的回退内容包含在静态外壳中。要同时将该组件排除在 <Link prefetch={true}> 之外,请在请求时访问之前等待 navigation()。请参阅保持预取为静态。

在构建时#

当你运行 next build 时,Next.js 会为每个已知分类(tops、shorts)预渲染布局,外加一次 await params 挂起的渲染,从而生成 [category] 的 App Shell。

它还会为每个分类下的每个已知产品(tops 下的 tee、shorts 下的 joggers)预渲染页面,外加一次 await params 挂起的渲染,从而生成 [product] 的 App Shell。

这些组合成:

  • /tops/tee、/shorts/joggers:完全静态的页面,两个参数均已知
  • /tops/[product]、/shorts/[product]:分类头部已渲染,产品显示回退内容
  • /[category]/[product]:两者都显示回退内容

外壳中的未知参数总是按照路由顺序排在最后。URL 中间不能出现未知段,因此不存在 /[category]/tee 这样的外壳。访问未列出的分类时,无论产品是什么,都会得到 /[category]/[product]。

在运行时#

访问者导航到 /tops/tee。两个参数都已预渲染。他们会得到一个完全静态的页面。

首次访问 /tops/overshirt。产品 overshirt 是未知的,但分类 tops 已预渲染。Next.js 提供 /tops/[product] 的 App Shell,其中分类头部已渲染。产品信息会流式传入。

首次访问 /shoes/basketball-shoes。两个参数都未预渲染。Next.js 提供通用的 /[category]/[product] App Shell。分类和产品都会流式传入。

首次访问之后,Next.js 会在后台使用现已已知的参数渲染这些路由。下一位访问相同 URL 的访客将获得升级后的结果。

当指向未列出 URL 的 <Link prefetch={true}> 进入视口时,Next.js 会在点击之前启动后台升级,就像首次访问一样,因此导航会落在升级后的结果上。

指向这些页面的链接需要设置 prefetch={true}。默认的 <Link> 只预取 App Shell,而指向同一路由的链接会共享该 App Shell。

小知识:未列出参数的 App Shell 从 Next.js 16.3 起开始提供。更早的版本会等待完整的服务器渲染后再发送响应。

等待完整的静态输出#

对于未列出的参数,ensureStatic = 'navigation' 会让第一个请求等待完整的静态页面。没有这个要求时,Next.js 可以在后台生成页面的同时返回一个预渲染的回退内容。Next.js 会存储完成的页面供后续请求使用。

升级会产生什么#

首次访问之后,Next.js 会在后台使用已知参数渲染页面,并尝试将静态边界尽可能向组件树深处推进:

  • 如果每次数据访问都被缓存且所有参数都已解析,则升级会生成一个完全静态的页面。
  • 如果所有参数都已解析,但渲染仍然到达了包裹在 <Suspense> 边界中的未缓存数据或 Request-time API(cookies()、headers()),则升级会生成一个带有这些回退内容的缓存页面。未缓存或特定于请求的部分会在请求时流式传入。

选择要预渲染的内容#

并非每个路由都需要预渲染。你预渲染的每一个页面都会增加构建工作量,并产生必须存储和部署的输出。许多路由可能在你的下一次部署之前都不会被访问,这使得这些工作变得不必要。

相反,应使用 generateStaticParams 预渲染那些最受益于提前准备好的路由,例如热门页面或可预测的内容。访问频率较低的路由会按需生成,并在首次访问后升级,这样你就不会把构建时间和存储空间花在可能永远不会被请求的页面上。

从 Pages Router 迁移而来#

如果你正在从 Pages Router 迁移:

  • getStaticPaths 中的 fallback: true 对应启用 Partial Prefetching 的 Cache Components。访问者会立即得到一个 <Suspense> 回退内容,Next.js 会存储完成的路由供后续访问使用。
  • fallback: 'blocking' 对应未启用 Partial Prefetching 的 Cache Components。在 <Suspense> 之外等待 params,以便第一个请求等待完成的路由,随后 Next.js 会将其存储起来供后续访问使用。
  • 不再需要 router.isFallback。预渲染步骤会生成一个静态外壳,你可以用 'use cache' 进一步扩大它。
  • 带 revalidate 的 getStaticProps 对应带 cacheLife 的 'use cache'。
  • getStaticPaths 对应 generateStaticParams。

后续步骤#

Next.js 中文网