NNext.js 中文网 GitHub

优化静态外壳

了解如何使用 Cache Components,在请求时内容流式传输期间保持布局、导航和有用的加载状态可用。

Cache Components 可以在请求时内容流式传入的同时预渲染静态外壳。该外壳可以保持路由的布局、导航、标题和聚焦的加载状态可见,而不是用一个宽泛的 fallback 替换整个页面。

在 Cache Components 之前编写的应用通常会在布局或页面的顶部附近 await 请求数据。启用 Cache Components 后,这些路由可能已经有了一个较小的静态外壳,有时仅由一个宽泛的加载状态组成。

在本指南中,你将学习如何通过追踪每次数据读取到需要它的 UI、缓存可复用的工作,以及将请求时工作移到聚焦的 <Suspense> 边界之后,来扩展外壳。这些模式让重要内容更早可用,并在页面其余部分流式传入时预留空间。

小知识: 本指南聚焦于 Cache Components,它支持下述的静态外壳和即时导航验证。许多底层模式,例如将数据访问移近需要它的 UI、使用聚焦的 <Suspense> 边界进行流式渲染、避免瀑布流以及设计稳定的加载状态,在其他 App Router 应用中同样有用。缓存指令和验证工作流需要 Cache Components。

使用优化器 skill(推荐)#

next-cache-components-optimizer skill 可通过编码代理应用本指南。它使用下方的 instant() 验证循环来捕获预期的静态外壳、验证当前行为,并将通过的测试保留为回归覆盖。

该 skill 也可以针对目标 UI 不会立即提交的客户端导航。它将相同的模式应用于发生变化的目标片段,然后通过真实链接验证指定的导航。如果目标已经具有即时 UI,而你希望在点击前包含更多特定于 URL 的内容,请改用优化预取。

安装该 skill:

Terminal
npx skills add vercel/next.js --skill next-cache-components-optimizer

然后向代理提供路由以及应位于其静态外壳中的 UI:

prompt
使用 next-cache-components-optimizer Skill 为 /[team]/settings 优化静态外壳。在初始加载时,设置框架和标题应立即可用。

前置条件#

先启用 cacheComponents 并解决路由的阻塞验证错误。迁移流程请参阅迁移到 Cache Components。

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

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

对于客户端导航,也可以考虑启用 Partial Prefetching。启用 Partial Prefetching 后,<Link prefetch={true}> 可以在点击前包含已缓存的特定于 URL 的内容,使更多 UI 在导航时立即可用。请参阅优化预取以选择要预取的内容。

模式#

以下模式可以让更多有用的 UI 在静态外壳中可用:

模式适用场景结果
将静态 UI 保留在外壳中UI 不需要数据该 UI 可以在静态外壳中渲染
流式传输请求时工作某个区域需要仅在请求时才知道的数据其最近的 <Suspense> fallback 可以先渲染
缓存可复用的工作结果可跨请求复用完成的结果可以在静态外壳中渲染

将静态 UI 保留在外壳中#

<Suspense> 边界控制当子级挂起时,其 fallback 会替换 UI 的哪一部分。静态 UI 位于边界内没有问题。但是,如果同一边界还包含缓慢或请求时工作,该 fallback 也会暂时替换静态 UI。

app/products/page.tsx
// 之前:一个加载状态替换整个页面
<Suspense fallback={<ProductsSkeleton />}>
  <h1>Products</h1>
  <p>Browse the latest products.</p>
  <LiveInventory />
</Suspense>

要让标题、导航、已缓存内容和其他稳定 UI 保持可见,请将它们从不需要归属的加载状态中取出。然后将边界下移到较小的、可能挂起的区域:

app/products/page.tsx
// 之后:只有库存使用加载状态
<main>
  <h1>Products</h1>
  <p>Browse the latest products.</p>
  <Suspense fallback={<InventorySkeleton />}>
    <LiveInventory />
  </Suspense>
</main>

当主要标题或其他 Largest Contentful Paint 候选元素依赖可复用数据时,缓存该数据,使完成的内容可以在外壳中渲染。如果数据必须等待请求,请保持其加载状态聚焦,以免拖慢页面其余部分。

流式传输请求时工作#

有些数据在请求到达前无法得知、必须为每个请求重新计算,或者缓存生命周期太短而无法预渲染。如果布局或页面在顶部附近 await 这些工作,可能会阻塞整个页面的渲染。请将需要结果的区域拆分出来,只让该区域挂起,以便页面其余部分可以先渲染。

下移数据访问#

在需要数据的逻辑 UI 区域中解析请求时数据。这可以是 await 数据的 Server Component,也可以是从服务端传入的 promise 进行解包的 Client Component。

将数据访问移入 Server Component。 当页面自身解析请求时数据时,其标题和其他独立 UI 在该工作完成前无法渲染:

app/products/[slug]/page.tsx
// 之前:请求时工作阻塞页面
export default async function ProductPage({
  params,
}: PageProps<'/products/[slug]'>) {
  const { slug } = await params
  const product = await db.products.findBySlug(slug)

  return (
    <main>
      <h1>Product</h1>
      <ProductDetails product={product} />
    </main>
  )
}

将 params、searchParams 或其他请求时数据读取移到代表相关 UI 区域的 Server Component 中。将该组件放在 <Suspense> 之后,以便其同级组件在工作解析时能够渲染:

app/products/[slug]/page.tsx
// 之后:只有商品区域等待
import { Suspense } from 'react'

export default function ProductPage({ params }: PageProps<'/products/[slug]'>) {
  return (
    <main>
      <h1>Product</h1>
      <Suspense fallback={<ProductSkeleton />}>
        <Product params={params} />
      </Suspense>
    </main>
  )
}

async function Product({
  params,
}: Pick<PageProps<'/products/[slug]'>, 'params'>) {
  const { slug } = await params
  const product = await db.products.findBySlug(slug)
  return <ProductDetails product={product} />
}

标题和商品 fallback 可以在请求时商品查询完成前渲染。cookies() 和 headers() 等请求 API 也可以移入一个聚焦的组件:

app/dashboard/layout.tsx
import { Suspense } from 'react'
import { cookies } from 'next/headers'

export default function DashboardLayout({ children }) {
  return (
    <DashboardShell>
      <Suspense fallback={<UserMenuSkeleton />}>
        <UserMenu />
      </Suspense>
      {children}
    </DashboardShell>
  )
}

async function UserMenu() {
  const cookieStore = await cookies()
  const menuStyle = cookieStore.get('menu-style')?.value ?? 'compact'

  return <DashboardMenu menuStyle={menuStyle} />
}

布局可以在 UserMenu 读取传入请求之前返回 DashboardShell。

内联解析 promise。 对于小区域,你无需仅为 await 一个 promise 而创建另一个组件。可以在边界内使用 .then() 内联解析 params、searchParams 或其他 promise:

app/products/page.tsx
<Suspense fallback={<ProductTabsSkeleton />}>
  {searchParams.then(({ tab = 'details' }) => (
    <ProductTabs activeTab={tab} />
  ))}
</Suspense>

将 promise 传递给 Client Component。 交互式 Client Component 可能需要服务端获取的数据。在其父级 await 这些数据也会拖慢父级的稳定 UI:

app/dashboard/page.tsx
// 之前:页面等待图表数据
export default async function DashboardPage() {
  const activity = await getActivity()

  return (
    <main>
      <h1>Dashboard</h1>
      <ActivityChart data={activity} />
    </main>
  )
}

发起请求但不 await 它,然后将 promise 传递给 <Suspense> 之后的 Client Component:

app/dashboard/page.tsx
// 之后:标题可以在图表等待时渲染
import { Suspense } from 'react'
import { getActivity } from '@/app/lib/data'
import { ActivityChart } from './activity-chart'

export default function DashboardPage() {
  const activityPromise = getActivity()

  return (
    <Suspense fallback={<ActivityChartSkeleton />}>
      <ActivityChart dataPromise={activityPromise} />
    </Suspense>
  )
}

Client Component 使用 React 的 use() 解包该 promise:

app/dashboard/activity-chart.tsx
'use client'

import { use } from 'react'

type Activity = { date: string; value: number }

export function ActivityChart({
  dataPromise,
}: {
  dataPromise: Promise<Activity[]>
}) {
  const activity = use(dataPromise)

  return <Chart data={activity} />
}

对于 URL 数据,Client Component 通常可以调用 useParams() 或 useSearchParams(),而不必接收 promise。这两个 Hook 在客户端导航期间会同步解析,因为路由器已经拥有 URL。

请参阅下移动态访问了解更多在靠近使用它的 UI 处解析请求时工作的示例。

设计加载状态#

在此重构之前,一个路由可能依赖一个 loading.tsx 文件来覆盖整个片段。当页面作为一个整体加载时,这通常足够。当你下移数据访问以显示更多完成的 UI 时,请使用聚焦的 <Suspense> 边界,并更审慎地选择其加载状态。loading.tsx 文件可以保留为外层 fallback,或在路由不再需要时移除。

分别显示独立区域。 当每个完成的区域具有可预测的尺寸且可单独出现时,使用同级边界。每个 fallback 都应预留其完成区域所需的空间:

app/account/page.tsx
<Suspense fallback={<AccountHeaderSkeleton />}>
  <AccountHeader />
</Suspense>
<Suspense fallback={<ActivitySkeleton />}>
  <Activity />
</Suspense>

分阶段显示相关区域。 当一组区域应先一起出现再显示更多细节时,或当单独显示高度可变的区域可能导致下方内容位移时,请嵌套边界:

app/account/page.tsx
<Suspense fallback={<AccountSkeleton />}>
  <AccountHeader />
  <Suspense fallback={<ActivitySkeleton />}>
    <Activity />
  </Suspense>
</Suspense>

React 仍然可以在同一次渲染中启动可独立到达的工作。嵌套只会改变显示顺序,不会使独立请求变为串行。

对于长度可变的内容,另一种选择是渲染一个可预测的折叠状态,并配上"显示更多"或"加载更多"控件,这样下方内容可以在不造成后续位移的情况下出现。

当路由使用并行插槽时,每个插槽都可以以自己的加载状态进行流式渲染。请参阅并行路由的加载和错误 UI。

为加载态和完成态 UI 使用相同的布局。 随着组件和响应式布局的变化,fallback 可能会与完成的 UI 产生偏差。请将拥有布局的容器保持在边界之外。在此示例中,骨架卡片和完成态商品卡片都使用相同的响应式网格:

app/products/page.tsx
<ProductGrid>
  <Suspense fallback={<ProductCardSkeletons />}>
    <ProductCards />
  </Suspense>
</ProductGrid>

小知识: 在你重构或更新 UI 时,骨架屏可能不再与完成态组件的尺寸或响应式布局匹配。将骨架屏放在组件旁边,或从同一文件中导出它,可以在该组件需要被 <Suspense> 包裹时更容易更新和复用。

只有当解析后的组件也没有视觉占位时(例如返回 null 的授权门),才使用空的 fallback。否则,请提供一个为完成态 UI 预留空间的 fallback。

相关的数据获取模式。 将工作拆分为流式区域后,这些模式可以防止请求本身启动得过晚:

  • 当多个独立请求必须留在同一区域时,使用并行数据获取同时启动它们。
  • 当 React 在渲染后期才遇到数据依赖时,使用预加载尽早启动它。

缓存可复用的工作#

在隔离了会阻塞页面的工作之后,请考虑每个异步子树是否真的需要为每个请求重新计算。缓存函数或组件并不会缓存其父级或同级。当结果可复用时,缓存该函数或组件,使其完成态 UI 可以在静态外壳中渲染。根据数据需要的新鲜程度为结果设置生命周期:

app/products/product-list.tsx
// 之前:查询为每个请求运行
export async function ProductList() {
  const products = await db.products.findMany()
  return <List products={products} />
}
app/products/product-list.tsx
// 之后:可复用的结果可以在外壳中渲染
import { cacheLife } from 'next/cache'

export async function ProductList() {
  'use cache'
  cacheLife('hours')

  const products = await db.products.findMany()
  return <List products={products} />
}

如果应用可以更改已缓存的结果,请使用按需重新验证将缓存读取与其写入关联起来。

相关缓存模式。 这些模式涵盖从请求派生的值、单个请求内的复用以及动态路由:

在缓存中了解更多关于缓存作用域和生命周期的内容。

在重构时遵循验证#

启用 Cache Components 后,next dev 会验证每次页面加载或客户端导航是否具有即时 UI。一个路由可能已有某个入口点的即时 UI,但另一个入口点却显示洞察。例如,共享布局中的 fallback 可能覆盖页面加载,却未覆盖该布局内的客户端导航。

如果在重构过程中出现洞察,说明该特定页面加载或客户端导航需要即时结果或 fallback。即使同一路由的另一个入口点已经即时,它也是上述模式或优化器 skill 的有用目标。建议的修复方案对应上述模式:

解决该洞察可使该入口点变为即时。它并不决定哪些 UI 应立即可用。使用 Navigation Inspector查看显示的内容,并应用上述模式以包含更多有用的 UI,或将路由和预期的即时 UI 提供给优化器 skill。

示例#

考虑一个团队设置路由,它在其布局和页面的顶部附近都 await 请求数据。在 Cache Components 之前编写的 App Router 应用中,这种结构可能看起来很自然。它也可能从 Pages Router延续而来,在那里路由级函数(如 getServerSideProps)会在渲染页面前加载数据。在 App Router 中,同样的结构不会在静态外壳中留下任何设置 UI。

该示例从一个布局和一个页面开始:

文件夹结构
app/[team]/settings/
├── layout.tsx
└── page.tsx

该布局在渲染设置框架前解析身份验证:

app/[team]/settings/layout.tsx
import { cookies, headers } from 'next/headers'
import { redirect } from 'next/navigation'

export default async function SettingsLayout({ children }) {
  const cookieStore = await cookies()
  const requestHeaders = await headers()
  const user = await getCurrentUser({ cookieStore, requestHeaders })

  if (!user) redirect('/login')

  return <SettingsShell>{children}</SettingsShell>
}

然后页面在渲染标题前等待其 URL 数据、团队设置和可复用的套餐描述:

app/[team]/settings/page.tsx
export default async function SettingsPage({
  params,
  searchParams,
}: PageProps<'/[team]/settings'>) {
  const { team } = await params
  const { section = 'profile' } = await searchParams
  const [settings, plans] = await Promise.all([
    getTeamSettings(team, section),
    db.plan.findMany(),
  ])

  return (
    <main>
      <h1>Settings</h1>
      <SettingsTabs activeSection={section} />
      <PlanList plans={plans} />
      <SettingsForm settings={settings} />
    </main>
  )
}

以下步骤保留完成的页面及其授权行为,同时让更多内容在静态外壳中可用。

第 1 步:将依赖 URL 的工作移到 Suspense 之后#

当前页面在渲染任何 UI 之前解析两个 URL promise:

app/[team]/settings/page.tsx
// 之前:URL 数据阻塞页面
export default async function SettingsPage({
  params,
  searchParams,
}: PageProps<'/[team]/settings'>) {
  const { team } = await params
  const { section = 'profile' } = await searchParams
  const settings = await getTeamSettings(team, section)

  return (
    <main>
      <h1>Settings</h1>
      <SettingsTabs activeSection={section} />
      <SettingsForm settings={settings} />
    </main>
  )
}

设置标签是交互式的,因此可以用 useSearchParams() 直接读取 URL。服务端渲染的表单接收 params 和 searchParams promise,并在需要其值的地方解析它们。

在预渲染期间,两个区域都依赖 URL,因此外层边界为这一组提供一个 fallback。一旦 URL 可用,标签就可以渲染。表单还要等待设置查询,因此嵌套边界会保持自身的加载状态可见,直到服务端工作完成:

app/[team]/settings/page.tsx
// 之后:标题在依赖 URL 的内容之前渲染
import { Suspense } from 'react'

export default function SettingsPage({
  params,
  searchParams,
}: PageProps<'/[team]/settings'>) {
  return (
    <main>
      <h1>Settings</h1>
      <Suspense fallback={<SettingsContentSkeleton />}>
        <SettingsTabs />
        <Suspense fallback={<SettingsFormSkeleton />}>
          <TeamSettings params={params} searchParams={searchParams} />
        </Suspense>
      </Suspense>
    </main>
  )
}

标签从 URL 读取当前活动的部分:

app/[team]/settings/settings-tabs.tsx
'use client'

import { useSearchParams } from 'next/navigation'

export function SettingsTabs() {
  const section = useSearchParams().get('section') ?? 'profile'

  return <Tabs activeSection={section} />
}

表单在启动依赖其值的查询之前会 await 两个 URL promise:

app/[team]/settings/team-settings.tsx
export async function TeamSettings({
  params,
  searchParams,
}: PageProps<'/[team]/settings'>) {
  const [{ team }, { section = 'profile' }] = await Promise.all([
    params,
    searchParams,
  ])
  const settings = await getTeamSettings(team, section)

  return <SettingsForm settings={settings} />
}

预渲染的外壳显示 SettingsContentSkeleton。一旦 URL 可用,标签会替换该 fallback,而嵌套的表单边界会保持加载状态,直到设置查询完成。

套餐查询不依赖任何 URL 值。将其移入同级组件,以便 React 在依赖 URL 的分支等待时启动它。此时它仍会为每个请求运行,因此保留一个临时边界:

app/[team]/settings/page.tsx
// 之后:独立的套餐查询与页面同时启动
import { Suspense } from 'react'

export default function SettingsPage({
  params,
  searchParams,
}: PageProps<'/[team]/settings'>) {
  return (
    <main>
      <h1>Settings</h1>
      <Suspense fallback={<PlanOptionsSkeleton />}>
        <PlanOptions />
      </Suspense>
      <Suspense fallback={<SettingsContentSkeleton />}>
        <SettingsTabs />
        <Suspense fallback={<SettingsFormSkeleton />}>
          <TeamSettings params={params} searchParams={searchParams} />
        </Suspense>
      </Suspense>
    </main>
  )
}
app/[team]/settings/plan-options.tsx
export async function PlanOptions() {
  const plans = await db.plan.findMany()
  return <PlanList plans={plans} />
}

标题直接渲染。PlanOptions 和依赖 URL 的设置分支可以独立开始。

第 2 步:将身份验证移到 Suspense 之后#

当前布局在渲染设置框架前解析请求 API:

app/[team]/settings/layout.tsx
// 之前:身份验证阻塞布局
import { cookies, headers } from 'next/headers'
import { redirect } from 'next/navigation'

export default async function SettingsLayout({ children }) {
  const cookieStore = await cookies()
  const requestHeaders = await headers()
  const user = await getCurrentUser({ cookieStore, requestHeaders })

  if (!user) redirect('/login')

  return <SettingsShell>{children}</SettingsShell>
}

改为将 cookies() 和 headers() 的读取移入 <Suspense> 之后的身份验证门。这样布局无需等待身份验证即可渲染设置框架:

app/[team]/settings/layout.tsx
// 之后:只有授权门等待请求
import { Suspense } from 'react'
import { cookies, headers } from 'next/headers'
import { redirect } from 'next/navigation'

export default function SettingsLayout({ children }) {
  return (
    <SettingsShell>
      <Suspense fallback={null}>
        <AuthGate />
      </Suspense>
      {children}
    </SettingsShell>
  )
}

async function AuthGate() {
  const [cookieStore, requestHeaders] = await Promise.all([
    cookies(),
    headers(),
  ])
  const user = await getCurrentUser({ cookieStore, requestHeaders })

  if (!user) redirect('/login')

  return null
}

AuthGate 是唯一需要请求值的组件,因此由它负责这些读取。它的边界让设置框架和页面保留在外壳中。空 fallback 适合这个边界,因为授权门也返回 null。

小知识: 如果诸如 unauthorized() 或 forbidden() 的授权中断在流式渲染开始后运行,它可以渲染自己的 UI,但响应状态仍为 200。如果 HTTP 401 或 403 状态很重要,请在流式渲染开始前检查访问权限。请参阅状态码。

布局重定向本身并不能保护数据库查询或 Server Action。请在页面使用的数据访问函数中保留授权检查,并在身份验证完成前只将安全的 UI 纳入外壳。完整模式请参阅使用 Cache Components 进行身份验证。

第 3 步:缓存可复用的套餐数据#

团队设置必须对每个请求保持最新且经过授权,因此它们继续作为 <Suspense> 之后的请求时工作。套餐描述在各团队间共享并按已知计划变更,因此 PlanOptions 可以缓存它们:

app/[team]/settings/plan-options.tsx
// 之前:查询为每个请求运行
export async function PlanOptions() {
  const plans = await db.plan.findMany()
  return <PlanList plans={plans} />
}
app/[team]/settings/plan-options.tsx
// 之后:可复用的套餐可以在外壳中渲染
import { cacheLife } from 'next/cache'

export async function PlanOptions() {
  'use cache'
  cacheLife('hours')

  const plans = await db.plan.findMany()
  return <PlanList plans={plans} />
}

PlanOptions 没有请求时依赖,因此 Next.js 可以在生成静态外壳时解析它。它现有的 <Suspense> 边界不会阻止这一点。该路由不需要 fallback,因此可以移除该边界。当缓存组件在请求时数据之后首次被访问时,请保留边界,以覆盖冷缓存。

如果写入操作更改了套餐描述,请在相应的变更中使用按需重新验证。

app/[team]/settings/page.tsx
<main>
  <h1>Settings</h1>
  <PlanOptions />
  <Suspense fallback={<SettingsContentSkeleton />}>
    <SettingsTabs />
    <Suspense fallback={<SettingsFormSkeleton />}>
      <TeamSettings params={params} searchParams={searchParams} />
    </Suspense>
  </Suspense>
</main>

重构完成后,该路由分三个阶段显示:

  1. 在静态外壳中。 标题和已缓存的套餐选项会渲染,而依赖 URL 的区域显示其 fallback。

```tsx <h1>Settings</h1>

```

  1. 一旦 URL 可用。 标签会替换内容骨架,而设置查询在其嵌套 fallback 后继续进行。

```tsx <h1>Settings</h1>

```

  1. 设置加载完成后。 完成态表单替换其骨架。

```tsx <h1>Settings</h1>

```

现在页面会立即渲染有用的 UI,同时特定于请求的内容会流入聚焦的 fallback。下一步是固定这一约定。

第 4 步:验证即时 UI#

使用 instant()阻止请求时服务端内容,并断言页面的哪些部分立即可用。请参阅初始页面加载了解水合如何影响这些断言。

e2e/settings-navigation.test.ts
import { expect, test, type Page } from '@playwright/test'
import { instant } from '@next/playwright'

async function expectInstantSettingsUI(page: Page) {
  await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible()
  await expect(page.getByTestId('plan-options')).toBeVisible()
  await expect(page.getByTestId('settings-tabs')).toBeVisible()
  await expect(page.getByTestId('settings-form-skeleton')).toBeVisible()
  await expect(page.getByTestId('settings-content-skeleton')).toHaveCount(0)
  await expect(page.getByTestId('team-settings-form')).toHaveCount(0)
}

test('shows settings UI before request-time work completes', async ({
  page,
  baseURL,
}) => {
  await instant(
    page,
    async () => {
      await page.goto('/acme/settings')
      await expectInstantSettingsUI(page)
    },
    { baseURL }
  )

  await expect(page.getByTestId('team-settings-form')).toBeVisible()
  await expect(page.getByTestId('settings-form-skeleton')).toHaveCount(0)
})

在回调中,标题和已缓存的套餐选项保持可见。水合已经根据浏览器 URL 渲染了标签,而 instant() 将请求时表单保留在 SettingsFormSkeleton 之后。最后的断言确认在暂停解除后,完成态表单替换了其加载状态。

针对 next start 的测试,请遵循生产环境配置。

完成后的路由应具有与原始路由相同的设置数据、重定向、错误状态和交互。

第 5 步:在即时 UI 中包含特定于 URL 的内容#

直接访问会从共享的静态外壳和 SettingsContentSkeleton 开始,因为路由在预渲染期间不知道 searchParams。一旦 URL 可用,标签会替换该 fallback。

在客户端导航期间,SettingsTabs 可以同步读取 URL。其他依赖目标 params 或 searchParams 的服务端内容不属于共享外壳。如果这些工作可缓存,则可以在点击前通过逐链接预取来解析它,而不是之后再进行流式传输。

当特定于 URL 的内容应在所选链接被点击前就绪时,请使用优化预取。该指南还介绍了如何根据工作成本选择预取策略。

Next.js 中文网