NNext.js 中文网 GitHub

优化预取

解析每个链接的 URL 数据,将 session 数据包含在 App Shell 中,或将开销较大的工作推迟到稍后的导航阶段。

预取会在用户导航到某个路由之前下载该路由的 JavaScript、CSS 和 RSC Payload,这样路由器无需等待往返即可渲染下一个路由。预取指南介绍了 App Router 默认预取的内容。

借助 Cache Components 和 Partial Prefetching,Next.js 会在客户端导航之前和期间分阶段加载服务器端渲染的输出。以下是路由的导航阶段:

  1. 默认的 <Link> 会加载路由的 App Shell。它保存路由的静态输出,对于读取 cookies() 或 headers() 的路由,还保存其特定于 session 的 UI。指向同一路由的链接会共享它。
  2. <Link prefetch={true}> 或 router.prefetch(href, { kind: 'full' }) 还会加载依赖于链接 URL 数据的静态或缓存内容,例如 searchParams 和 params,这些内容是共享的 shell 无法包含的。
  3. 当用户点击该链接时,导航会渲染路由的其余部分。

使用 prefetch() 和 navigation() 将开销较大的工作移到稍后的阶段。要要求某个阶段在整个路由中保持静态,请参阅保持页面静态。

使用优化器技能(推荐)#

next-partial-prefetching-optimizer 技能可让编码智能体应用本指南。它会在 instant() 测试中为选定链接定义应准备好的 UI,验证当前行为,并使测试通过。

安装该技能:

Terminal
npx skills add vercel/next.js --skill next-partial-prefetching-optimizer

然后向智能体提供来源、目标以及应立即可用的 UI:

prompt
让从 / 导航到 /search?q=react 时搜索结果即时呈现。使用 next-partial-prefetching-optimizer 技能。

在应用这些优化之前,启用 Cache Components 和 partialPrefetching:

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

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

export default nextConfig

如果该路由尚未针对即时导航进行结构化,请先从即时导航指南开始,以验证其缓存结构。

在预取时解析 URL 数据#

设置 <Link prefetch={true}> 以在导航前解析该链接的 URL 数据。目标路由必须使用 Partial Prefetching,可通过 partialPrefetching 全局启用,或通过 prefetch = 'partial' 按段启用。

对于自定义链接,调用 router.prefetch(href, { kind: 'full' }) 来请求相同的按链接阶段。调用不带 kind 选项的 router.prefetch(href) 只会请求 App Shell。

位于 / 的用户会看到指向 /search?q=react 和 /search?q=next 的链接,每个链接都通过 prefetch={true} 选择加入:

app/page.tsx
import Link from 'next/link'

export default function Home() {
  return (
    <nav>
      <Link href="/search?q=react" prefetch={true}>
        React
      </Link>
      <Link href="/search?q=next" prefetch={true}>
        Next.js
      </Link>
    </nav>
  )
}

'auto' 等同于省略 prefetch 或传入 undefined。在条件表达式中,对于应保持默认 App Shell 预取的链接,返回 'auto':

app/page.tsx
<Link href={href} prefetch={isFeatured ? true : 'auto'} />

仅当你想禁用某个链接的预取时,才使用 prefetch={false}。

/search 页面会渲染一个静态标题和一个基于查询的 <Results> 列表。search() 函数按查询缓存结果,以便后续请求可以重用它们。

app/search/page.tsx
import { Suspense } from 'react'

export default function SearchPage({ searchParams }: PageProps<'/search'>) {
  return (
    <>
      <h1>Search</h1>
      <Suspense fallback={<ResultsSkeleton />}>
        <Results searchParams={searchParams} />
      </Suspense>
    </>
  )
}

async function Results({
  searchParams,
}: {
  searchParams: PageProps<'/search'>['searchParams']
}) {
  const { q } = await searchParams
  return <ResultList items={await search(q)} />
}

async function search(q: string) {
  'use cache'
  return db.search(q)
}

不使用 prefetch={true} 时,App Shell 会渲染 <h1> 并显示 <Results> 的后备内容。查询会在点击后解析,并将结果流式传入。

当链接上设置了 prefetch={true} 时,路由器会请求一次按链接预取,在点击前解析 <Results>。q 值来自链接的 URL,这在预取时是已知的,缓存的 search(q) 调用会提供结果。当用户点击时,结果会立即渲染,而不会显示后备内容。

Next.js 会在预取中包含静态和缓存的内容,直到遇到未缓存的读取。然后它会包含来自周围 <Suspense> 边界的后备内容。该边界已经通过为即时导航构建路由结构就位。

生成按链接预取的代价是每个可预取链接调用一次服务器,因此它是按链接选择加入的。在所有内容都可静态渲染的页面上,Next.js 会从静态缓存中提供预取。访问非静态数据的页面会按预取生成,除非该访问被推迟到导航阶段。

小知识: 冷缓存(首次访问或过期后)意味着服务器仍然需要计算缓存结果。用户可能会在首次导航时看到加载指示器。只要缓存是热的,后续导航就是即时的。

与 searchParams 一样,params 也需要 <Suspense> 边界,即使其值是由 generateStaticParams预定义的。静态已知的参数仍然属于某一个 URL。带有 prefetch={true} 的按链接预取会解析 generateStaticParams 未覆盖的值。

在 shell 中包含 session 数据#

prefetch={true} 解析 URL 数据。session 数据则单独处理。读取 cookies() 或 headers() 的路由(包括通过 "use cache: private")会获得一个包含其 session 数据的 App Shell,它在客户端按 session 缓存,并在导航时即可使用,无需按链接预取。

基于 session 数据的查找需要缓存生命周期,就像 search(q) 对 URL 所做的那样。以一个读取 cookie、然后基于它查找内容的仪表盘导航为例:

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

export default function DashboardLayout({
  children,
}: LayoutProps<'/dashboard'>) {
  return (
    <div>
      <Suspense fallback={<nav>Loading...</nav>}>
        <UserNav />
      </Suspense>
      <main>{children}</main>
    </div>
  )
}

App Shell 渲染可以读取 session 数据。但是,"use cache" 不能在缓存函数内部调用 cookies(),因此请使用以下模式之一:

  • 当查找结果在多个 session 之间共享时,使用提取并传递。
  • 当查找结果与单个 session 绑定时,使用 "use cache: private"。

提取并传递#

在缓存函数外部读取 cookie,并将该值作为参数传入。cookies() 调用保持在缓存作用域之外,参数跨越边界,缓存函数具有确定性的签名。缓存条目以该参数为键,共享该值的 session 会共享该条目。

app/dashboard/user-nav.tsx
import { cookies } from 'next/headers'

async function UserNav() {
  const team = (await cookies()).get('team')?.value
  const topics = await getTopics(team)
  return (
    <nav>
      {topics.map((topic) => (
        <a key={topic.id} href={topic.href}>
          {topic.label}
        </a>
      ))}
    </nav>
  )
}

async function getTopics(team: string | undefined) {
  'use cache'
  return db.topics.forTeam(team)
}

在直接访问时,<UserNav> 会显示其后备内容,直到查找完成。在导航时,App Shell 已经解析了它,因为 team cookie 是 shell 可以读取的 session 数据。由于同一团队的 session 共享缓存条目,对底层数据的流量随团队数量而非 session 数量伸缩。

任何没有缓存指令的内容仍会在导航后流式传入。shell 只保存能在导航前准备好的内容,而不是整个页面。它只会推进到缓存结构所允许的程度。

"use cache: private"#

当查找与单个 session 绑定时,使用 "use cache: private"。它为直接读取 cookie、header 或其他运行时数据的函数分配缓存生命周期。结果仅在浏览器中缓存,作用域限定在该 session。

app/dashboard/user-nav.tsx
import { cookies } from 'next/headers'

async function UserNav() {
  const user = await getUser()
  return <nav>{user.name}</nav>
}

async function getUser() {
  'use cache: private'
  const session = (await cookies()).get('session')?.value
  return db.users.findBySession(session)
}

这里 cookies() 位于缓存函数内部,这只有在 "use cache: private" 下才有效。当运行时数据无法在调用点提取时,请使用相同的模式。例如,认证辅助函数可能会将 Date.now() 与令牌的过期时间进行比较,或者 session 辅助函数可能会在其自身代码中读取 cookie。

作用域内的所有内容共享相同的生命周期。尽量将 "use cache: private" 放在尽可能靠近运行时数据访问的位置。

将工作推迟到稍后阶段#

App Shell 由指向某个路由的链接共享。按链接预取会针对可见的 <Link prefetch={true}> 或手动调用 router.prefetch(href, { kind: 'full' }) 运行,而导航则在用户点击时运行。对于用户从未点击的链接,生成开销较大的工作可能并不值得。

未缓存的工作已经被排除在预取之外。对于可缓存的工作,next/cache 导出了一些函数,用于推迟每次调用下方的代码:

在下图中,灰色虚线轮廓表示 Suspense 后备内容,蓝色表示延迟工作渲染后的内容:

这两个函数仅在运行时渲染期间生效,因此它们不会改变完全静态的路由。每次调用都会推迟等待它的组件及其子组件。较早的阶段会渲染最近的 <Suspense> 后备内容,当延迟的子树在其阶段运行时会替换该后备内容。与 connection() 不同,这两个函数都不会使子树依赖于请求,因此其中的函数仍然可以使用 use cache。请参阅 navigation() 与 connection() 的区别。

将开销较大的 session 数据排除在 App Shell 之外#

再以仪表盘为例。基于 session 的排名开销较大,而每个指向仪表盘的默认 <Link> 都会为 shell 生成它。在排名之前 await prefetch(),这样只有 <Link prefetch={true}> 才会在点击前解析它:

app/dashboard/recommendations.tsx
import { cookies } from 'next/headers'
import { prefetch } from 'next/cache'

async function Recommendations() {
  const session = (await cookies()).get('session')?.value
  await prefetch()
  const items = await rank(session)
  return <List items={items} />
}

async function rank(session?: string) {
  'use cache: private'
  return db.recommendations.rank({ session })
}

session 在 prefetch() 之前读取,因此它仍然在 shell 中解析。App Shell 不会生成排名。默认的 <Link> 包含 <Suspense> 后备内容,排名会在导航期间替换它。<Link prefetch={true}> 会在点击前解析排名。在这两种情况下,rank 都会保留其缓存生命周期。

这两个函数都不能在缓存作用域内 await,因此该指令应放在其下方调用的函数上,就像这里的 rank 一样。

等待导航#

以一个收件箱为例,其中每个可见的会话线程都使用 <Link prefetch={true}>。预取应包含会话主题,但在用户打开之前获取每条消息的正文会浪费工作。

将最新消息渲染在它自己的 <Suspense> 边界中,并在加载它之前 await navigation():

app/inbox/[threadId]/thread.tsx
import { Suspense } from 'react'
import { navigation } from 'next/cache'
import { getLatestMessage, getThreadSummary } from '@/lib/mail'

export async function Thread({ threadId }: { threadId: string }) {
  const thread = await getThreadSummary(threadId)

  return (
    <article>
      <h1>{thread.subject}</h1>
      <Suspense fallback={<p>Loading message...</p>}>
        <LatestMessage threadId={threadId} />
      </Suspense>
    </article>
  )
}

async function LatestMessage({ threadId }: { threadId: string }) {
  await navigation()
  const message = await getLatestMessage(threadId)
  return <p>{message.body}</p>
}

两个查询都保持缓存:

lib/mail.ts
import { db } from '@/lib/db'

export async function getThreadSummary(threadId: string) {
  'use cache'
  return db.thread.findUniqueOrThrow({
    select: { subject: true },
    where: { id: threadId },
  })
}

export async function getLatestMessage(threadId: string) {
  'use cache'
  return db.message.findFirstOrThrow({
    orderBy: { sentAt: 'desc' },
    select: { body: true },
    where: { threadId },
  })
}

按链接预取包含缓存的主题和消息后备内容。缓存的消息正文会在用户打开会话时加载,然后在后续访问时保持可用。

让子树保持未缓存也会使其不参与预取,但它也会在导航时失去缓存生命周期。对于 use cache 内容,五分钟或更长的 stale 时间可让客户端路由器在首次导航后重用它。低于该时间时,每次导航都会重新获取它。

保持预取为静态#

当对 cookies()、headers()、params 和 searchParams 的每次读取都位于 navigation() 下方时,运行时预取将产生与构建时相同的输出。因此 Next.js 可以从静态输出提供预取。CDN 可以缓存该输出,因此指向该路由的链接不需要服务器计算。

仪表盘无法采用这种结构,因为 <UserNav> 会在 shell 中读取 team cookie。而带有静态头部的信息流可以:

app/feed/page.tsx
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { navigation } from 'next/cache'

export default function Page() {
  return (
    <>
      <FeedHeader /> 
      <Suspense fallback={<p>Loading stories...</p>}>
        <Stories />
      </Suspense>
    </>
  )
}

async function Stories() {
  await navigation()
  const topic = (await cookies()).get('topic')?.value ?? 'all'
  return <StoryList items={await getStories(topic)} />
}

在 navigation() 下方读取 cookie 不会使按链接预取按请求渲染,因为该读取在预取期间本来就不会解析。prefetch() 和 App Shell 也是如此。当每次 cookies() 和 headers() 读取都位于 prefetch() 下方时,shell 会从静态输出提供。读取 params 或 searchParams 不需要运行时 shell。URL 数据被排除在共享 shell 之外,但除非它位于 navigation() 下方,否则它可能导致按链接预取在运行时渲染。

每次调用都会推迟一个子树。要为整个路由要求静态输出,使后续的更改不会重新引入请求时渲染,请设置 ensureStatic。保持页面静态指南会逐步介绍每个层级。

测试预取和延迟加载的内容#

使用 instant() 来检查目标路由预取的 UI。Playwright 指南涵盖了安装、测试配置和导航注意事项。

在采用 Partial Prefetching时,请在启用该功能之前运行此测试,并在之后重新运行相同的断言。这样可以在其实现迁移到 App Shell 或按链接预取时,保留从旧版完整预取中选定的 UI。

在回调内部,点击链接,等待目标 URL,并断言哪些内容可用。在回调释放导航之后,断言延迟的内容最终会渲染:

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

test('prefetches the product summary but not reviews', async ({ page }) => {
  await page.goto('/products')

  await instant(page, async () => {
    await page.click('a[href="/products/baseball-cap"]')
    await page.waitForURL((url) => url.pathname === '/products/baseball-cap')

    await expect(
      page.getByRole('heading', { name: 'Baseball Cap' })
    ).toBeVisible()
    await expect(page.getByTestId('product-summary')).toBeVisible()
    await expect(page.getByTestId('reviews')).toHaveCount(0)
  })

  await expect(page.getByTestId('reviews')).toBeVisible()
})

在 instant() 回调运行期间,动态内容会暂停。在此示例中,产品摘要是预取 UI 的一部分,而评论则等待导航。最后的断言确认评论在暂停释放后会渲染。

在开发环境中,位于 <Suspense> 之外的 prefetch() 或 navigation() 调用会显示一条 Instant Insight。完全预渲染的路由不受影响,但该洞察会指出:如果路由后续需要运行时渲染,该调用将推迟内容而没有后备内容。generateMetadata() 和 generateViewport() 中的调用有单独的洞察。

权衡取舍#

在以下路由上使用 prefetch={true}:

  • 组件树的一部分依赖于 URL 数据:完整的 URL、searchParams,或未被 generateStaticParams解析的 params
  • 该部分组件树具有已知的缓存生命周期(可以用 "use cache" 或 "use cache: private" 表达)
  • 流量足以证明按链接调用服务器是值得的

预取缓存数据不会改变其新鲜度行为。如果某个变更可以更新数据,请为缓存结果添加标签并使其失效。

当预取无法产生比 App Shell 更好的 UI 时,请跳过它。每个可见的 <Link prefetch={true}> 都可能唤醒服务器,只有当页面在点击前有更多内容准备就绪时,这种开销才值得:

  • 路由很少或根本不依赖 URL 数据。App Shell 已经使导航即时完成。
  • 依赖的内容必须在每次请求时保持新鲜。预渲染会停在同一个 <Suspense> 后备内容处,因此无论哪种方式用户看到的 UI 都是相同的。
  • 该路由很少被导航到。无论是否点击,你都要为每个可见链接付出代价。

按链接预取是尽力而为的。它只对在点击前完成的导航有帮助。在慢速连接、包含许多链接的信息流或直接访问时,用户导航时它可能尚未准备好,此时导航会回退到 App Shell。

当同时显示许多指向某个路由的链接时(例如卡片网格),每个 <Link prefetch={true}> 都会在该链接进入视口时预取其自身内容,因此网格会为每张卡片发出一次这样的服务器请求。请改为基于意图进行预取。悬停触发的预取只会获取用户可能点击的链接。默认的 <Link>(不带 prefetch={true})只加载 App Shell,因此不会带来这种开销。

App Shell使用 prefetch={true} 的按链接预取导航
范围每个路由一个每个可见的 <Link prefetch={true}> 一个每次点击一个
内容路由的渲染输出,减去按链接的数据以及 prefetch() 或 navigation() 下方的工作App Shell 加上按链接的 URL 数据和 prefetch() 下方的工作,不包括 navigation() 下方的工作其余所有内容,包括 navigation() 下方的工作
开销受路由数量限制受可见链接数量限制受导航次数限制
作用默认预取点击前渲染更多内容完成路由

推迟工作避免为可能永远不会使用的预取生成内容。代价是导航时可能会显示最近的 <Suspense> 后备内容,同时延迟的内容正在渲染。

下一步#

Next.js 中文网