预取
了解如何在 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 |
| 客户端缓存 TTL | 5 分钟(默认) | 关闭,除非启用 |
| 点击时的服务器往返 | 否 | 是,在 shell 之后流式传输 |
小知识: 在初始导航期间,浏览器会获取 HTML、JavaScript 和 React Server Components (RSC) Payload。对于后续导航,浏览器将获取 Server Component 的 RSC Payload 和 Client Component 的 JS 包。
自动预取#
import Link from 'next/link'
export default function NavLink() {
return <Link href="/about">About</Link>
}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 维护一个小任务队列,按以下顺序预取:
- 视口中的链接
- 显示用户意图的链接(悬停或触摸)
- 较新的链接替换较旧的链接
- 滚动出屏幕的链接被丢弃
调度器会优先考虑可能发生的导航,同时尽量减少无用的下载。
小知识:启用 实验性
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() 下方的可缓存内容。
'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> 在进入视口时进行预取。要仅预取用户可能访问的链接,请将预取延迟到用户悬停在链接上时进行:
'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#
你可以扩展 <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>,但页脚中的链接在进入视口时可能不需要预取。
故障排除#
在预取期间触发意外的副作用#
如果你的 layout 或页面不是纯函数并且有副作用(例如跟踪分析),Next.js 可能会在预取路由时运行它们,而不是在用户访问页面时。
要避免这种情况,请将副作用移到 useEffect hook 或由 Client Component 触发的 Server Action 中。
之前:
import { trackPageView } from '@/lib/analytics'
export default function Layout({ children }: { children: React.ReactNode }) {
// 这会在预取期间运行
trackPageView()
return <div>{children}</div>
}import { trackPageView } from '@/lib/analytics'
export default function Layout({ children }) {
// 这会在预取期间运行
trackPageView()
return <div>{children}</div>
}之后:
'use client'
import { useEffect } from 'react'
import { trackPageView } from '@/lib/analytics'
export function AnalyticsTracker() {
useEffect(() => {
trackPageView()
}, [])
return null
}'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>
)
}import { AnalyticsTracker } from '@/app/ui/analytics-tracker'
export default function Layout({ children }) {
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>
)
}'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>
)
}