预取

预取使应用程序中不同路由之间的导航感觉即时。Next.js 默认会根据应用程序代码中使用的链接智能地进行预取。

本指南将解释预取的工作原理并展示常见的实现模式。

• 自动预取
• 手动预取
• 悬停触发的预取
• 扩展或弹出链接
• 禁用预取

预取如何工作？

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

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

导航到新页面时，不会有完整的页面重新加载或浏览器加载指示器。相反，Next.js 会执行客户端过渡，使页面导航感觉即时。

预取静态与动态路由

须知：在初始导航期间，浏览器会获取 HTML、JavaScript 和 React 服务器组件 (RSC) Payload。对于后续导航，浏览器将获取服务器组件的 RSC Payload 和客户端组件的 JS bundle。

自动预取

import Link from 'next/link'
 
export default function NavLink() {
  return <Link href="/about">About</Link>
}

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

手动预取

要手动预取，请从 next/navigation 导入 useRouter 钩子，并调用 router.prefetch() 来预热视口之外的路由或响应分析、悬停、滚动等操作。

'use client'
 
import { useRouter } from 'next/navigation'
import { CustomLink } from '@components/link'
 
export function PricingCard() {
  const router = useRouter()
 
  return (
    <div onMouseEnter={() => router.prefetch('/pricing')}>
      {/* other UI elements */}
      <CustomLink href="/pricing">View Pricing</CustomLink>
    </div>
  )
}

如果目的是在组件加载时预取 URL，请参阅扩展或拒绝链接[示例]。

悬停触发的预取

请谨慎行事：扩展 Link 意味着您需要维护预取、缓存失效和可访问性问题。仅当默认设置不足时才继续。

Next.js 默认尝试进行正确的预取，但高级用户可以根据自己的需要弹出并修改。您可以在性能和资源消耗之间进行控制。

例如，您可能只需要在悬停时触发预取，而不是在进入视口时（默认行为）

'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} 在用户显示意图后恢复默认（静态）预取。

扩展或弹出链接

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

或者，您可以使用useRouter 来重新创建一些原生 <Link> 行为。但是，请注意这会使您负责维护预取和缓存失效。

'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 来导航到目标。

禁用预取

您可以完全禁用某些路由的预取，以更精细地控制资源消耗。

'use client'
 
import Link, { LinkProps } from 'next/link'
 
function NoPrefetchLink({
  prefetch,
  ...rest
}: LinkProps & { children: React.ReactNode }) {
  return <Link {...rest} prefetch={false} />
}

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

预取优化

须知：布局去重和预取调度是即将进行的优化的一部分。目前通过 experimental.clientSegmentCache 标志在 Next.js canary 中可用。

客户端缓存

Next.js 将预取的 React 服务器组件 payload 存储在内存中，以路由段作为键。在同级路由之间导航时（例如 /dashboard/settings → /dashboard/analytics），它会重用父布局并仅获取更新的叶子页面。这减少了网络流量并提高了导航速度。

预取调度

Next.js 维护一个小型任务队列，按以下顺序预取：

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

调度器优先处理可能的导航，同时最大程度地减少未使用的下载。

部分预渲染 (PPR)

启用 PPR 后，页面会分为静态 shell 和流式动态部分。

• 可以预取的 shell 会立即流式传输
• 动态数据在准备好后流式传输
• 数据失效（revalidateTag、revalidatePath）会悄无声息地刷新相关的预取。

故障排除

预取期间触发不需要的副作用

如果您的布局或页面不是纯粹的并具有副作用（例如跟踪分析），这些副作用可能会在路由预取时触发，而不是在用户访问页面时触发。

为避免这种情况，您应该将副作用移动到 useEffect 钩子或从客户端组件触发的服务器 Action 中。

之前:

import { trackPageView } from '@/lib/analytics'
 
export default function Layout({ children }: { children: React.ReactNode }) {
  // This runs during prefetch
  trackPageView()
 
  return <div>{children}</div>
}

之后:

'use client'
 
import { useEffect } from 'react'
import { trackPageView } from '@/lib/analytics'
 
export function AnalyticsTracker() {
  useEffect(() => {
    trackPageView()
  }, [])
 
  return null
}

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

防止过多的预取

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

在某些情况下，您可能希望阻止这种情况，以避免不必要的资源使用，例如在渲染大量链接列表时（例如无限滚动表格）。

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

<Link prefetch={false} href={`/blog/${post.id}`}>
  {post.title}
</Link>

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

为了在不完全禁用预取的情况下减少资源使用，您可以将预取推迟到用户将鼠标悬停在链接上时。这只针对用户可能访问的链接。

'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>
  )
}