优化静态外壳
了解如何使用 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:
npx skills add vercel/next.js --skill next-cache-components-optimizer然后向代理提供路由以及应位于其静态外壳中的 UI:
使用 next-cache-components-optimizer Skill 为 /[team]/settings 优化静态外壳。在初始加载时,设置框架和标题应立即可用。前置条件#
先启用 cacheComponents 并解决路由的阻塞验证错误。迁移流程请参阅迁移到 Cache Components。
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。
// 之前:一个加载状态替换整个页面
<Suspense fallback={<ProductsSkeleton />}>
<h1>Products</h1>
<p>Browse the latest products.</p>
<LiveInventory />
</Suspense>要让标题、导航、已缓存内容和其他稳定 UI 保持可见,请将它们从不需要归属的加载状态中取出。然后将边界下移到较小的、可能挂起的区域:
// 之后:只有库存使用加载状态
<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 在该工作完成前无法渲染:
// 之前:请求时工作阻塞页面
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> 之后,以便其同级组件在工作解析时能够渲染:
// 之后:只有商品区域等待
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 也可以移入一个聚焦的组件:
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:
<Suspense fallback={<ProductTabsSkeleton />}>
{searchParams.then(({ tab = 'details' }) => (
<ProductTabs activeTab={tab} />
))}
</Suspense>将 promise 传递给 Client Component。 交互式 Client Component 可能需要服务端获取的数据。在其父级 await 这些数据也会拖慢父级的稳定 UI:
// 之前:页面等待图表数据
export default async function DashboardPage() {
const activity = await getActivity()
return (
<main>
<h1>Dashboard</h1>
<ActivityChart data={activity} />
</main>
)
}发起请求但不 await 它,然后将 promise 传递给 <Suspense> 之后的 Client Component:
// 之后:标题可以在图表等待时渲染
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:
'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 都应预留其完成区域所需的空间:
<Suspense fallback={<AccountHeaderSkeleton />}>
<AccountHeader />
</Suspense>
<Suspense fallback={<ActivitySkeleton />}>
<Activity />
</Suspense>分阶段显示相关区域。 当一组区域应先一起出现再显示更多细节时,或当单独显示高度可变的区域可能导致下方内容位移时,请嵌套边界:
<Suspense fallback={<AccountSkeleton />}>
<AccountHeader />
<Suspense fallback={<ActivitySkeleton />}>
<Activity />
</Suspense>
</Suspense>React 仍然可以在同一次渲染中启动可独立到达的工作。嵌套只会改变显示顺序,不会使独立请求变为串行。
对于长度可变的内容,另一种选择是渲染一个可预测的折叠状态,并配上"显示更多"或"加载更多"控件,这样下方内容可以在不造成后续位移的情况下出现。
当路由使用并行插槽时,每个插槽都可以以自己的加载状态进行流式渲染。请参阅并行路由的加载和错误 UI。
为加载态和完成态 UI 使用相同的布局。 随着组件和响应式布局的变化,fallback 可能会与完成的 UI 产生偏差。请将拥有布局的容器保持在边界之外。在此示例中,骨架卡片和完成态商品卡片都使用相同的响应式网格:
<ProductGrid>
<Suspense fallback={<ProductCardSkeletons />}>
<ProductCards />
</Suspense>
</ProductGrid>小知识: 在你重构或更新 UI 时,骨架屏可能不再与完成态组件的尺寸或响应式布局匹配。将骨架屏放在组件旁边,或从同一文件中导出它,可以在该组件需要被
<Suspense>包裹时更容易更新和复用。
只有当解析后的组件也没有视觉占位时(例如返回 null 的授权门),才使用空的 fallback。否则,请提供一个为完成态 UI 预留空间的 fallback。
相关的数据获取模式。 将工作拆分为流式区域后,这些模式可以防止请求本身启动得过晚:
缓存可复用的工作#
在隔离了会阻塞页面的工作之后,请考虑每个异步子树是否真的需要为每个请求重新计算。缓存函数或组件并不会缓存其父级或同级。当结果可复用时,缓存该函数或组件,使其完成态 UI 可以在静态外壳中渲染。根据数据需要的新鲜程度为结果设置生命周期:
// 之前:查询为每个请求运行
export async function ProductList() {
const products = await db.products.findMany()
return <List products={products} />
}// 之后:可复用的结果可以在外壳中渲染
import { cacheLife } from 'next/cache'
export async function ProductList() {
'use cache'
cacheLife('hours')
const products = await db.products.findMany()
return <List products={products} />
}如果应用可以更改已缓存的结果,请使用按需重新验证将缓存读取与其写入关联起来。
相关缓存模式。 这些模式涵盖从请求派生的值、单个请求内的复用以及动态路由:
- 要使用来自
cookies()、headers()或其他运行时 API 的值缓存结果,请在缓存作用域之外读取该值并将其作为参数传入。 - 要在单个服务端请求中对匹配的调用去重,而不跨请求保留结果,请使用 React
cache()。 - 要预渲染已知的动态路由并按需生成其他路由,请参阅使用 Cache Components 的 ISR。
在缓存中了解更多关于缓存作用域和生命周期的内容。
在重构时遵循验证#
启用 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该布局在渲染设置框架前解析身份验证:
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 数据、团队设置和可复用的套餐描述:
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:
// 之前: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 可用,标签就可以渲染。表单还要等待设置查询,因此嵌套边界会保持自身的加载状态可见,直到服务端工作完成:
// 之后:标题在依赖 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 读取当前活动的部分:
'use client'
import { useSearchParams } from 'next/navigation'
export function SettingsTabs() {
const section = useSearchParams().get('section') ?? 'profile'
return <Tabs activeSection={section} />
}表单在启动依赖其值的查询之前会 await 两个 URL promise:
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 的分支等待时启动它。此时它仍会为每个请求运行,因此保留一个临时边界:
// 之后:独立的套餐查询与页面同时启动
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>
)
}export async function PlanOptions() {
const plans = await db.plan.findMany()
return <PlanList plans={plans} />
}标题直接渲染。PlanOptions 和依赖 URL 的设置分支可以独立开始。
第 2 步:将身份验证移到 Suspense 之后#
当前布局在渲染设置框架前解析请求 API:
// 之前:身份验证阻塞布局
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> 之后的身份验证门。这样布局无需等待身份验证即可渲染设置框架:
// 之后:只有授权门等待请求
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。如果 HTTP401或403状态很重要,请在流式渲染开始前检查访问权限。请参阅状态码。
布局重定向本身并不能保护数据库查询或 Server Action。请在页面使用的数据访问函数中保留授权检查,并在身份验证完成前只将安全的 UI 纳入外壳。完整模式请参阅使用 Cache Components 进行身份验证。
第 3 步:缓存可复用的套餐数据#
团队设置必须对每个请求保持最新且经过授权,因此它们继续作为 <Suspense> 之后的请求时工作。套餐描述在各团队间共享并按已知计划变更,因此 PlanOptions 可以缓存它们:
// 之前:查询为每个请求运行
export async function PlanOptions() {
const plans = await db.plan.findMany()
return <PlanList plans={plans} />
}// 之后:可复用的套餐可以在外壳中渲染
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,因此可以移除该边界。当缓存组件在请求时数据之后首次被访问时,请保留边界,以覆盖冷缓存。
如果写入操作更改了套餐描述,请在相应的变更中使用按需重新验证。
<main>
<h1>Settings</h1>
<PlanOptions />
<Suspense fallback={<SettingsContentSkeleton />}>
<SettingsTabs />
<Suspense fallback={<SettingsFormSkeleton />}>
<TeamSettings params={params} searchParams={searchParams} />
</Suspense>
</Suspense>
</main>重构完成后,该路由分三个阶段显示:
- 在静态外壳中。 标题和已缓存的套餐选项会渲染,而依赖 URL 的区域显示其 fallback。
```tsx <h1>Settings</h1>
```
- 一旦 URL 可用。 标签会替换内容骨架,而设置查询在其嵌套 fallback 后继续进行。
```tsx <h1>Settings</h1>
```
- 设置加载完成后。 完成态表单替换其骨架。
```tsx <h1>Settings</h1>
```
现在页面会立即渲染有用的 UI,同时特定于请求的内容会流入聚焦的 fallback。下一步是固定这一约定。
第 4 步:验证即时 UI#
使用 instant()阻止请求时服务端内容,并断言页面的哪些部分立即可用。请参阅初始页面加载了解水合如何影响这些断言。
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 的内容应在所选链接被点击前就绪时,请使用优化预取。该指南还介绍了如何根据工作成本选择预取策略。