NNext.js 中文网 GitHub

prefetch

使用 prefetch 函数将运行时工作推迟到逐链接预取或导航时执行。

调用 await prefetch() 会将其下方的运行时工作排除在路由的 App Shell 之外。这些工作可以在逐链接预取或导航期间运行,而最近的 <Suspense> 边界的 fallback 则在外壳中渲染。

对于本应由 App Shell 渲染但生成成本较高的内容,请使用 prefetch()。静态预渲染仍会在其输出中包含这些内容。

用法#

该函数需要 Cache Components,如果未启用会抛出错误。如果没有 Partial Prefetching,路由就没有 App Shell,因此该函数不起作用。通过采用 Partial Prefetching 可全局启用,或逐个路由启用。

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

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

export default nextConfig

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

  1. 默认的 <Link> 加载 App Shell,其中包含路由中不依赖 URL 的部分。
  2. 可选的 <Link prefetch={true}> 或 router.prefetch(href, { kind: 'full' }) 还可以加载依赖该链接 URL 的内容。
  3. 当用户点击该链接时,导航会渲染路由的其余部分。

在运行时渲染期间,await prefetch() 会将内容排除在 App Shell 之外,使其在逐链接预取或导航期间渲染。静态预渲染仍可包含这些内容。

在 Partial Prefetching 下,调用不带 kind: 'full' 的 router.prefetch(href) 只请求 App Shell,不会渲染 await prefetch() 下方的内容。

要让内容也不出现在逐链接预取中、仅在导航时渲染,请使用 navigation()。

小知识:prefetch() 只推迟一个子树。要要求整个路由使用静态 App Shell,请使用 ensureStatic = 'shell'。有关完整示例,请参阅保持页面静态。

prefetch() 上方的一切都在 App Shell 中渲染,下方的一切则在逐链接预取或导航时渲染。推迟作用范围限于 await 它的组件及其下方子树:兄弟分支照常在外壳中渲染。请将其放在要推迟的工作之前,并用 <Suspense> 包裹该组件:

app/dashboard/page.tsx
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, prefetch } from 'next/cache'

export default function Page() {
  return (
    <>
      <Suspense fallback={<p>Loading greeting...</p>}>
        <Greeting /> 
      </Suspense>
      <Suspense fallback={<p>Loading recommendations...</p>}>
        
        <Recommendations />
      </Suspense>
    </>
  )
}

async function Greeting() {
  const session = (await cookies()).get('session')?.value
  return <p>{session ? 'Welcome back' : 'Welcome'}</p>
}

async function Recommendations() {
  await prefetch() // 下方的运行时工作在逐链接预取或导航时渲染
  const items = await getRecommendations()
  return <List items={items} />
}

async function getRecommendations() {
  'use cache: private'
  cacheLife('hours')
  const session = (await cookies()).get('session')?.value
  return db.recommendations.rank({ session })
}
app/dashboard/page.js
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, prefetch } from 'next/cache'

export default function Page() {
  return (
    <>
      <Suspense fallback={<p>Loading greeting...</p>}>
        <Greeting /> 
      </Suspense>
      <Suspense fallback={<p>Loading recommendations...</p>}>
        
        <Recommendations />
      </Suspense>
    </>
  )
}

async function Greeting() {
  const session = (await cookies()).get('session')?.value
  return <p>{session ? 'Welcome back' : 'Welcome'}</p>
}

async function Recommendations() {
  await prefetch() // 下方的运行时工作在逐链接预取或导航时渲染
  const items = await getRecommendations()
  return <List items={items} />
}

async function getRecommendations() {
  'use cache: private'
  cacheLife('hours')
  const session = (await cookies()).get('session')?.value
  return db.recommendations.rank({ session })
}

问候语读取 session 并留在 App Shell 中。推荐内容也在 getRecommendations 中读取它,因此该读取会与排序一起被推迟。移除 prefetch() 后,它们就会成为每个指向该路由的链接都会加载的 App Shell 的一部分。

将该指令放在其下方调用的函数上,如此处的 getRecommendations。不允许在缓存作用域内 await prefetch(),例如 use cache 或 use cache: private。

prefetch() 与 connection() 的区别#

connection() 函数会等待真实请求。它将后续代码排除在预渲染和预取之外,使这些工作依赖于请求。

await prefetch() 会将后续代码排除在 App Shell 之外。它可以在逐链接预取期间解析,而不会使这些工作依赖于请求。因此,await prefetch() 之后调用的函数可以使用 "use cache" 并保持其缓存生命周期,而无需为每个指向该路由的链接生成结果。

当工作必须为真实请求运行时,请使用 connection()。当工作可复用但只应为选定的逐链接预取或导航运行时,请使用 prefetch()。

何时使用#

当 prefetch() 下方的内容生成成本高、且不应在指向该路由的每个 <Link> 都会加载的 App Shell 中生成时,请使用 prefetch()。

生成 App Shell 不会运行该代码,因此其上游请求直到逐链接预取或导航时才会发出。

让内容不缓存也能将其排除在外壳之外,但会放弃其缓存生命周期,且无法在逐链接预取期间提供。使用 prefetch() 时,内容可以通过 use cache 或 use cache: private 缓存、设置生命周期,并推迟到逐链接预取或导航。

未缓存的读取、stale 时间较短的值,以及位于 params 或 searchParams 之后的任何内容,本身就会被排除在外壳之外。

保持 App Shell 静态#

当对 cookies() 和 headers() 的每次读取都位于 prefetch() 下方时,外壳预取所触发的预渲染无法生成比构建时已生成的静态输出更多的内容,因此外壳会改为由该输出提供。以这种方式组织路由是一项可选优化:静态响应可以缓存在 CDN 中,因此指向该路由的默认 <Link> 完全不消耗服务端 CPU。解析 params 或 searchParams 的路由则会得到相应的预渲染,上面的示例也是如此:其问候语在外壳中读取 session,因此外壳每位访问者渲染一次,只有推荐内容被推迟。

小知识#

  • 该函数对页面的初次加载没有影响。
  • 与 connection() 不同,它不会将子树标记为依赖于请求。await prefetch() 下方的内容仍可完全缓存,并可包裹在 use cache 中。
  • 在 <Suspense> 边界之外的调用会在开发环境中显示一条 Instant Insight。完全预渲染的路由不受影响,但该洞察会指出:如果路由之后需要运行时渲染,该调用会在没有 fallback 的情况下推迟内容。
  • 在 use cache、use cache: private、unstable_cache()、after()、generateStaticParams 或 Client Component 中调用它会抛出错误。
  • 在设置了 prefetch 路由段配置 的 page 或 layout 中,请以其他名称导入该函数,例如 import { prefetch as prefetchStage } from 'next/cache',因为两者都名为 prefetch。

参考#

类型#

ts
function prefetch(): Promise<void>

参数#

  • 该函数不接受任何参数。

返回值#

一个 Promise<void>,无需消费它。

版本历史#

版本变更
v16.4.0引入 prefetch,取代早期 canary 版本中使用的 unstable_prefetch 名称。
Next.js 中文网