NNext.js 中文网 GitHub

预取

了解如何在 Next.js 中配置预取

预取使路由之间的导航感觉瞬间完成。默认情况下,Next.js 会根据应用代码中的链接预取路由。

本指南解释预取的工作原理、Next.js 为你预取的内容以及如何控制它:

使用部分预取(Partial Prefetching)? 启用 partialPrefetching 后,<Link> 默认预取每条路由的 App Shell,而不是整个页面。请参阅下文的部分预取以及采用部分预取了解采用路径。

预取是如何工作的?#

在路由之间导航时,浏览器会请求页面所需的资源,如 HTML 和 JavaScript 文件。预取是指在导航到新路由之前提前获取这些资源的过程。

Next.js 会根据路由自动将你的应用拆分为更小的 JavaScript 块。与传统的 SPA 不同,它不会预先加载所有代码,而只加载当前路由所需的代码。这减少了初始加载时间,同时应用的其他部分在后台加载。当你点击链接时,新路由的资源已经加载到浏览器缓存中。

导航到新页面时,不会出现整页重新加载或浏览器加载旋转图标。相反,Next.js 会执行客户端过渡(client-side transition),使页面导航感觉瞬间完成。

Next.js 自动预取的内容#

Next.js 在生产环境中自动预取。当每个 <Link> 进入视口时,Next.js 会预取其背后的路由,并安排工作,以免满是链接的页面淹没网络。每条路由预取多少取决于该路由是静态还是动态,并且在启用部分预取后会有所变化。

预取静态路由与动态路由#

在没有 Cache Components 的情况下,静态路由会被完整预取,而动态路由会被跳过,除非它具有 loading.js 边界。

静态页面动态页面
是否预取是,完整路由否,除非具有 loading.js
客户端缓存 TTL5 分钟(默认)关闭,除非启用
点击时的服务器往返否是,在 shell 之后流式传输

小知识: 在初始导航期间,浏览器会获取 HTML、JavaScript 和 React Server Components (RSC) Payload。对于后续导航,浏览器将获取 Server Component 的 RSC Payload 和 Client Component 的 JS 包。

自动预取#

app/ui/nav-link.tsx
import Link from 'next/link'

export default function NavLink() {
  return <Link href="/about">About</Link>
}
app/ui/nav-link.js
import Link from 'next/link'

export default function NavLink() {
  return <Link href="/about">About</Link>
}
上下文预取的 payload客户端缓存 TTL
无 loading.js整个页面5 分钟(staleTimes.static)
有 loading.js从 Layout 到第一个加载边界默认关闭(staleTimes.dynamic)

自动预取仅在生产环境中运行。使用 prefetch={false} 禁用,或使用禁用预取中的包装器。

预取调度#

Next.js 维护一个小任务队列,按以下顺序预取:

  1. 视口中的链接
  2. 显示用户意图的链接(悬停或触摸)
  3. 较新的链接替换较旧的链接
  4. 滚动出屏幕的链接被丢弃

调度器会优先考虑可能发生的导航,同时尽量减少无用的下载。

小知识:启用 实验性 useOffline 配置后,当应用从连接中断中恢复时,待处理的预取会通过此队列恢复。

客户端缓存#

Next.js 将预取的 React Server Component payload 存储在内存中,以路由段为键。当在同级路由之间导航时(例如 /dashboard/settings → /dashboard/analytics),Next.js 会重用父级 layout,只获取更新的叶子页面。

部分预取(Partial Prefetching)#

通过 partialPrefetching 配置(需要 Cache Components)启用部分预取后,预取从上面的全有或全无模型切换为每条路由的 App Shell:

  • 每条路由一个 shell,跨链接共享。 <Link> 预取路由的 App Shell,其中包含其静态和会话输出。指向同一路由的任意数量的链接都会重用该 shell,当第一个链接进入视口时获取一次,因此包含许多链接的页面比完整预取每条路由发出的预取请求更少。
  • 其余内容流式传入。 未缓存的数据在导航后流式传入,位于 shell 的 <Suspense> 边界之后。链接还可以使用 prefetch={true} 在预取时解析其 URL 数据(searchParams、params)。
  • 立即失效会清除预取。 来自 Server Action 的数据失效(updateTag、revalidatePath 或立即过期的 revalidateTag)会清除预取的路由。请参阅客户端缓存行为了解各种重新验证 API 之间的差异。

有关行为变化和推荐的采用路径,请参阅采用部分预取。有关使用 prefetch={true} 在导航前解析缓存的 URL 特定内容,请参阅优化预取。

控制预取#

Next.js 使用默认设置进行预取,当这些默认值不符合你的资源预算或导航模式时,你可以按链接进行调整。

手动预取#

要手动预取,请从 next/navigation 导入 useRouter hook,然后调用 router.prefetch() 来预热视口之外的路由,或响应分析、悬停或滚动。

使用部分预取时,router.prefetch(href) 请求与默认 <Link> 相同的 App Shell。传入 { kind: 'full' } 还会请求按链接阶段的预取,与 <Link prefetch={true}> 相匹配。按链接阶段可以包含 await prefetch() 下方的可缓存内容。

tsx
'use client'

import { useRouter } from 'next/navigation'
import { CustomLink } from '@components/link'

export function PricingCard() {
  const router = useRouter()

  return (
    <div onMouseEnter={() => router.prefetch('/pricing', { kind: 'full' })}>
      
      <CustomLink href="/pricing">View Pricing</CustomLink>
    </div>
  )
}

要在组件加载时预取 URL,请参阅扩展或弹出 link。

悬停触发的预取#

谨慎操作: 扩展 Link 意味着你需要自行维护预取、缓存失效和可访问性问题。仅在默认设置不足时才这样做。

默认情况下,<Link> 在进入视口时进行预取。要仅预取用户可能访问的链接,请将预取延迟到用户悬停在链接上时进行:

tsx
'use client'

import Link from 'next/link'
import { useState } from 'react'

export function HoverPrefetchLink({
  href,
  children,
}: {
  href: string
  children: React.ReactNode
}) {
  const [active, setActive] = useState(false)

  return (
    <Link
      href={href}
      prefetch={active ? null : false}
      onMouseEnter={() => setActive(true)}
    >
      {children}
    </Link>
  )
}

一旦用户表现出意图,prefetch={null} 会恢复默认预取。

使用部分预取时,请改用 prefetch={active ? true : 'auto'}。'auto' 值会在用户表现出意图之前保持共享 App Shell 的预取,而 true 会在用户表现出意图后、导航前解析缓存的 URL 特定内容。在表现出意图之前使用 false 会禁用 App Shell 预取。

你可以扩展 <Link> 组件以创建自己的自定义预取策略。例如,使用 ForesightJS 库,它通过预测用户光标的方向来预取链接。

或者,你可以使用 useRouter 来重新创建一些原生 <Link> 行为。但请注意,这意味着你需要自行维护预取和缓存失效。

tsx
'use client'

import { useRouter } from 'next/navigation'
import { useEffect } from 'react'

function ManualPrefetchLink({
  href,
  children,
}: {
  href: string
  children: React.ReactNode
}) {
  const router = useRouter()

  useEffect(() => {
    let cancelled = false
    const poll = () => {
      if (!cancelled) router.prefetch(href, { onInvalidate: poll })
    }
    poll()
    return () => {
      cancelled = true
    }
  }, [href, router])

  return (
    <a
      href={href}
      onClick={(event) => {
        event.preventDefault()
        router.push(href)
      }}
    >
      {children}
    </a>
  )
}

当 Next.js 怀疑缓存数据已过时时,会调用 onInvalidate,以便你刷新预取。

小知识: a 标签会触发整页导航。使用 onClick 阻止它,然后调用 router.push 在客户端进行导航。

禁用预取#

你可以对某些路由完全禁用预取,以便更精细地控制资源消耗。

tsx
'use client'

import Link, { LinkProps } from 'next/link'

function NoPrefetchLink({
  prefetch,
  ...rest
}: LinkProps & { children: React.ReactNode }) {
  return <Link {...rest} prefetch={false} />
}

例如,你可能仍希望在应用中一致地使用 <Link>,但页脚中的链接在进入视口时可能不需要预取。

故障排除#

在预取期间触发意外的副作用#

如果你的 layout 或页面不是纯函数并且有副作用(例如跟踪分析),Next.js 可能会在预取路由时运行它们,而不是在用户访问页面时。

要避免这种情况,请将副作用移到 useEffect hook 或由 Client Component 触发的 Server Action 中。

之前:

app/dashboard/layout.tsx
import { trackPageView } from '@/lib/analytics'

export default function Layout({ children }: { children: React.ReactNode }) {
  // 这会在预取期间运行
  trackPageView()

  return <div>{children}</div>
}
app/dashboard/layout.js
import { trackPageView } from '@/lib/analytics'

export default function Layout({ children }) {
  // 这会在预取期间运行
  trackPageView()

  return <div>{children}</div>
}

之后:

app/ui/analytics-tracker.tsx
'use client'

import { useEffect } from 'react'
import { trackPageView } from '@/lib/analytics'

export function AnalyticsTracker() {
  useEffect(() => {
    trackPageView()
  }, [])

  return null
}
app/ui/analytics-tracker.js
'use client'

import { useEffect } from 'react'
import { trackPageView } from '@/lib/analytics'

export function AnalyticsTracker() {
  useEffect(() => {
    trackPageView()
  }, [])

  return null
}
app/dashboard/layout.tsx
import { AnalyticsTracker } from '@/app/ui/analytics-tracker'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <AnalyticsTracker />
      {children}
    </div>
  )
}
app/dashboard/layout.js
import { AnalyticsTracker } from '@/app/ui/analytics-tracker'

export default function Layout({ children }) {
  return (
    <div>
      <AnalyticsTracker />
      {children}
    </div>
  )
}

防止过多预取#

使用 <Link> 组件时,Next.js 会自动预取视口中的链接。

你可能希望阻止这种情况以避免不必要的资源使用,例如渲染大量链接列表时(如无限滚动表格)。

你可以通过将 <Link> 组件的 prefetch 属性设置为 false 来禁用预取。

app/ui/no-prefetch-link.tsx
<Link prefetch={false} href={`/blog/${post.id}`}>
  {post.title}
</Link>

但是,这意味着静态路由只会在点击时获取,而动态路由将等待服务器渲染后再导航。

要在不完全禁用预取的情况下减少资源使用,你可以将预取延迟到用户悬停在链接上时进行。这仅针对用户可能访问的链接。

app/ui/hover-prefetch-link.tsx
'use client'

import Link from 'next/link'
import { useState } from 'react'

export function HoverPrefetchLink({
  href,
  children,
}: {
  href: string
  children: React.ReactNode
}) {
  const [active, setActive] = useState(false)

  return (
    <Link
      href={href}
      prefetch={active ? null : false}
      onMouseEnter={() => setActive(true)}
    >
      {children}
    </Link>
  )
}
app/ui/hover-prefetch-link.js
'use client'

import Link from 'next/link'
import { useState } from 'react'

export function HoverPrefetchLink({ href, children }) {
  const [active, setActive] = useState(false)

  return (
    <Link
      href={href}
      prefetch={active ? null : false}
      onMouseEnter={() => setActive(true)}
    >
      {children}
    </Link>
  )
}
Next.js 中文网