采用部分预取
了解如何启用部分预取,以及 <Link> 会发生哪些变化。
部分预取改变了 <Link> 为 Cache Components 路由下载的内容。启用部分预取后,<Link> 会预取路由的 App Shell:即其静态内容和不依赖于 URL 的缓存内容。Next.js 为每个路由构建一个 App Shell,并将其复用于指向该路由的每个链接,而不是像以前那样分别预取每个链接。
要预取比 App Shell 更多的内容,链接可以通过 <Link prefetch={true}> 选择启用按链接预取。这样预取就可以解析依赖于 params、searchParams 或完整 URL 的、特定于 URL 的缓存内容。
在此过程中,Next.js 会在开发环境中显示即时导航洞察,并指出需要修改的链接或路由。
小知识:部分预取仅在启用
cacheComponents时有效。
使用采用技能(推荐)#
next-partial-prefetching-adoption 技能通过编码代理来推动这一采用过程。它会审查你的 <Link prefetch={true}> 调用,在提供生产测试环境时捕获要保留的预取 UI(通过 instant() 测试),然后启用该标志并检查每个路由是否出现本指南涵盖的洞察。
安装该技能:
npx skills add vercel/next.js --skill next-partial-prefetching-adoption然后向代理提供以下提示:
Adopt Partial Prefetching in this project using the next-partial-prefetching-adoption skill.或手动采用#
要手动采用现有应用:
- 审查现有的完整预取,并选择每个目标中应继续预取的部分。你可以使用
instant()测试 来添加回归覆盖。 - 启用
partialPrefetching。对于较大的迁移,你可以在全局标志关闭的情况下逐步采用。预取期间的动态数据洞察会识别出每个仍使用旧式完整预取的目标。 - 将 URL 数据移到 Suspense 之后,解决 Suspense 之外的 URL 数据洞察。
- (可选)在导航后流式传入内容不够用的路由上预取 URL 数据。
这两种洞察都仅在开发环境中出现,绝不会阻止构建。它们会出现在开发浮层中,并带有指向各修复文档页面的修复卡片。如果某个路由尚未准备好采用,可以从其页面或布局中导出 instant = false,使该路由退出即时导航验证,稍后再回来处理。
启用部分预取#
小知识:在现有应用中,请在启用部分预取之前,先审查
<Link prefetch={true}>所交付的 UI。这些链接使用旧式完整预取,启用部分预取会改变它们的行为。
在 next.config.ts 中启用 partialPrefetching:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfig启用该标志后,使用默认行为、prefetch="auto" 或 prefetch={true} 的链接都会预取目标的 App Shell。带有 prefetch={true} 的链接还可以解析特定于 URL 的缓存内容,但它不再包含旧式完整预取中未缓存的动态内容。新项目可以直接启用该标志,因为它们没有需要迁移的旧式完整预取。
小知识:当启用了
cacheComponents但未设置partialPrefetching值时,Next.js 会记录一条警告,要求你将其设置为true或false。只有在你按本指南完成迁移期间需要保持之前的预取行为时,才设置为false。这两个功能将在下一个主要版本中全面启用,届时这些选项将被移除。
<Link> 的变化#
<Link> 属性 | 之前(Cache Components 默认) | 采用部分预取后 |
|---|---|---|
<Link href="/x"> | 预取缓存的页面渲染结果。 | 预取 /x 共享的 App Shell。 |
<Link href="/x" prefetch> | 预取缓存的页面渲染结果以及任何动态内容。 | 预取 App Shell,并在 /x 读取时通过按链接预取预取特定于 URL 的缓存内容。 |
<Link href="/x" prefetch={false}> | 禁用该链接的预取。 | 不变。仍然禁用。 |
App Shell 在指向给定路由的所有链接之间共享,与动态参数无关,因此渲染许多指向同一目标的 <Link> 不会成倍增加工作量。
迁移现有的完整预取#
在部分预取出现之前,prefetch 有效值为 true 的 <Link> 会预取完整的目标,包括未缓存的动态内容。这包括 prefetch={true}、单独的 prefetch 属性,以及解析为 true 的包装属性或条件属性。默认值 prefetch="auto" 和 prefetch={false} 不使用旧式完整预取。
旧式完整预取可能包含比导航所需更多的 UI。在大多数情况下,目标顶部的主要内容应在导航前就可用,而次要内容或频繁变化的内容可以在之后流式传入。
小知识:
cookies()和headers()不会将预取绑定到 URL。它们按会话而非按链接变化,因此 App Shell 仍然承载会话内容。只有params和searchParams是 URL 数据,它们按链接变化,不能包含在共享的 App Shell 中。
通过测试验证预取的 UI#
要以编程方式验证迁移,可以使用 instant() 测试来捕获应从现有完整预取中保持可用的 UI。请测试确切的来源链接,因为指向同一目标的不同链接可能使用不同的预取设置:
import { expect, test } from '@playwright/test'
import { instant } from '@next/playwright'
test('preserves the prefetched product summary', async ({ page }) => {
await page.goto('/products')
await instant(page, async () => {
const link = page.getByRole('link', { name: 'Baseball Cap' })
await expect(link).toBeVisible()
await link.click()
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()
})
})请在禁用 partialPrefetching 的生产构建上运行此基线测试,因为自动预取不会在 next dev 中运行。然后在采用该目标后重新运行同一测试。如果失败,说明所选 UI 不再被预取。请缓存应保持可用的可复用数据或子树,并将通过的测试保留为回归覆盖。
静态或已缓存的内容#
输出已经在 App Shell 中。移除现在多余的 prefetch={true}:
// 之前
<Link href="/about" prefetch={true}>About</Link>
// 之后
<Link href="/about">About</Link>未缓存的内容#
使用 use cache 将其缓存,使其包含在 App Shell 中,然后从链接中移除 prefetch={true}:
// 之前
export default async function Page() {
const res = await fetch('https://api.example.com/products')
return <ProductList products={await res.json()} />
}// 之前
export default async function Page() {
const res = await fetch('https://api.example.com/products')
return <ProductList products={await res.json()} />
}// 之后 - 已缓存,因此 App Shell 会携带它
async function getProducts() {
'use cache'
const res = await fetch('https://api.example.com/products')
return res.json()
}
export default async function Page() {
return <ProductList products={await getProducts()} />
}// 之后 - 已缓存,因此 App Shell 会携带它
async function getProducts() {
'use cache'
const res = await fetch('https://api.example.com/products')
return res.json()
}
export default async function Page() {
return <ProductList products={await getProducts()} />
}小知识:App Shell 会携带
stale时间至少为 5 分钟的缓存内容,上面使用的default配置文件以及除seconds之外的所有预设都满足这一条件。生命周期更短的内容会在导航后流式传入。请参阅预渲染行为。
会话内容#
位于 cookies() 或 headers() 之后的内容按会话而非按链接变化,并且会话数据会在 App Shell 中解析,因此缓存的会话内容仍会被包含。请在缓存函数之外读取会话值并将其传入,然后从链接中移除 prefetch={true}:
// 之前
import { Suspense } from 'react'
import { cookies } from 'next/headers'
async function TeamTopics() {
const team = (await cookies()).get('team')?.value
const topics = await db.topics.forTeam(team)
return <TopicList topics={topics} />
}
export default function Page() {
return (
<Suspense fallback={<Skeleton />}>
<TeamTopics />
</Suspense>
)
}// 之前
import { Suspense } from 'react'
import { cookies } from 'next/headers'
async function TeamTopics() {
const team = (await cookies()).get('team')?.value
const topics = await db.topics.forTeam(team)
return <TopicList topics={topics} />
}
export default function Page() {
return (
<Suspense fallback={<Skeleton />}>
<TeamTopics />
</Suspense>
)
}// 之后 - 查询在会话值之后被缓存
import { Suspense } from 'react'
import { cookies } from 'next/headers'
async function getTopics(team: string | undefined) {
'use cache'
return db.topics.forTeam(team)
}
async function TeamTopics() {
const team = (await cookies()).get('team')?.value
return <TopicList topics={await getTopics(team)} />
}
export default function Page() {
return (
<Suspense fallback={<Skeleton />}>
<TeamTopics />
</Suspense>
)
}// 之后 - 查询在会话值之后被缓存
import { Suspense } from 'react'
import { cookies } from 'next/headers'
async function getTopics(team) {
'use cache'
return db.topics.forTeam(team)
}
async function TeamTopics() {
const team = (await cookies()).get('team')?.value
return <TopicList topics={await getTopics(team)} />
}
export default function Page() {
return (
<Suspense fallback={<Skeleton />}>
<TeamTopics />
</Suspense>
)
}URL 数据#
URL 数据(params、searchParams)按链接变化,因此依赖于它的内容不能包含在共享的 App Shell 中,而会在导航后从其 <Suspense> 边界之后流式传入。链接保留 prefetch={true},预取 URL 数据一节介绍如何在点击之前预取内容。
实时内容#
对实时内容的预取在点击时就已经过时,因此没有需要保留的内容。请移除 prefetch={true},让内容从其 <Suspense> 边界之后流式传入。
| 目标 | 建议 |
|---|---|
| 完全静态,或内容已缓存 | 移除现在多余的 prefetch={true}。 |
| 交付了你希望在点击前保留的未缓存内容 | 使用 use cache 缓存它,然后移除 prefetch={true}。 |
交付了依赖于 cookies() 或 headers() 的内容 | 在会话值之后缓存查询,然后移除 prefetch={true}。 |
| 读取 URL 数据,或具有依赖于它的缓存内容 | 保留 prefetch={true},以便在点击前解析内容。 |
| 交付必须按请求保持新鲜的实时内容 | 移除 prefetch={true},让内容流式传入。 |
逐步采用#
采用不必一次完成。prefetch = 'partial' 是作用域为单个路由的全局标志,因此在全局标志仍然关闭的情况下,你可以逐个采用并部署每个目标。
在目标选择加入部分预取之前,prefetch={true} 会执行旧式完整预取。在开发环境中通过其中一个链接导航时,会出现预取期间的动态数据洞察,指出目标并指向其修复方案:
每张卡片都可以点击,并会打开一个包含模式、代码示例和权衡取舍的页面。
- 从一个目标开始。保留预期的预取 UI,并使用上面的模式更新其
prefetch={true}链接。然后在其页面或布局中添加export const prefetch = 'partial',这会清除指向该路由的每个链接的洞察:
```tsx filename="app/dashboard/page.tsx" switcher // 之前 export default function Page() {
return <Dashboard />} ```
```jsx filename="app/dashboard/page.js" switcher // 之前 export default function Page() {
return <Dashboard />} ```
```tsx filename="app/dashboard/page.tsx" switcher // 之后 - 在未启用全局标志的情况下采用 export const prefetch = 'partial'
export default function Page() {
return <Dashboard />} ```
```jsx filename="app/dashboard/page.js" switcher // 之后 - 在未启用全局标志的情况下采用 export const prefetch = 'partial'
export default function Page() {
return <Dashboard />} ```
> 小知识:如果页面或布局已经调用了 prefetch(),请以其他名称导入它,例如 import { prefetch as prefetchStage } from 'next/cache',以免与 prefetch 导出冲突。
- 部署更改。指向已采用目标的链接会加载 App Shell,而洞察会继续在你尚未处理的目标上出现。
- 重复此过程,直到范围内的每个目标都已采用,然后启用标志。
现在,按路由导出的 prefetch = 'partial' 已经多余了。可以使用 remove-partial-prefetch codemod 一次性移除它们,它会从每个 page 和 layout 中删除 export const prefetch = 'partial':
npx @next/codemod@canary remove-partial-prefetch ./app小知识:在
src/项目中请传入./src/app。路径错误时只会报告0 ok而不会报错,因此请检查文件数量。
该 codemod 只移除 'partial' 值,其他值(如 prefetch = 'force-disabled')会保留。
将 URL 数据移到 Suspense 之后#
启用标志后,Next.js 会在开发环境中随着你的导航验证每个 App Shell。App Shell 在指向某个路由的所有链接之间共享,因此它不能包含只属于单个 URL 的数据。在 <Suspense> 边界之外读取 params 或 searchParams 会将 App Shell 绑定到链接的 URL,并出现 Suspense 之外的 URL 数据洞察,指出路由并指向其修复方案:
该洞察绝不会阻止构建,因此这一步骤可以在标志开启后的任何时间进行。在 next dev 中加载每个路由以检查是否出现该洞察。
修复方法是将路由中与 URL 无关的部分保留在边界之外,并将 params 或 searchParams 的读取移入用 <Suspense> 包裹的子组件:
// 之前 - 在顶层等待 params 会将 App Shell 绑定到某个 URL
export default async function Page({ params }: PageProps<'/products/[slug]'>) {
const { slug } = await params
const product = await getProduct(slug)
return (
<ProductLayout>
<Details product={product} />
</ProductLayout>
)
}// 之前 - 在顶层等待 params 会将 App Shell 绑定到某个 URL
export default async function Page({ params }) {
const { slug } = await params
const product = await getProduct(slug)
return (
<ProductLayout>
<Details product={product} />
</ProductLayout>
)
}// 之后 - 将 promise 向下传递而不等待它
import { Suspense } from 'react'
import { ProductDetails } from './product-details'
export default function Page({ params }: PageProps<'/products/[slug]'>) {
return (
<ProductLayout>
<Suspense fallback={<DetailsSkeleton />}>
<ProductDetails params={params} />
</Suspense>
</ProductLayout>
)
}// 之后 - 将 promise 向下传递而不等待它
import { Suspense } from 'react'
import { ProductDetails } from './product-details'
export default function Page({ params }) {
return (
<ProductLayout>
<Suspense fallback={<DetailsSkeleton />}>
<ProductDetails params={params} />
</Suspense>
</ProductLayout>
)
}子组件在边界内等待该 promise:
export async function ProductDetails({
params,
}: Pick<PageProps<'/products/[slug]'>, 'params'>) {
const { slug } = await params
const product = await getProduct(slug)
return <Details product={product} />
}export async function ProductDetails({ params }) {
const { slug } = await params
const product = await getProduct(slug)
return <Details product={product} />
}边界之外的所有内容都保留在共享的 App Shell 中,只有特定于 URL 的区域按每次导航渲染。请再次加载或导航到该路由,以确认洞察已消失且页面仍能呈现有意义的 UI。
小知识:在
generateMetadata中读取params或searchParams会改为出现generateMetadata()中的 URL 数据洞察。
预取 URL 数据#
依赖于 URL 数据(params、searchParams)的内容不能包含在共享的 App Shell 中,因此会在导航后流式传入。对于带有 prefetch={true} 的链接,按链接预取会在点击之前解析该内容,代价是每个可预取链接都会调用一次服务器。要使内容在预取时可解析,请使用 use cache 在读取操作之后缓存它。对于读取 searchParams 的搜索页面:
// 之前 - 结果在导航后流式传入
import { Suspense } from 'react'
async function getResults(query: string) {
const res = await fetch(`https://api.example.com/search?q=${query}`)
return res.json()
}
async function Results({
searchParams,
}: Pick<PageProps<'/search'>, 'searchParams'>) {
const { q } = await searchParams
return <ResultList results={await getResults(q)} />
}
export default function Page({ searchParams }: PageProps<'/search'>) {
return (
<Suspense fallback={<Skeleton />}>
<Results searchParams={searchParams} />
</Suspense>
)
}// 之前 - 结果在导航后流式传入
import { Suspense } from 'react'
async function getResults(query) {
const res = await fetch(`https://api.example.com/search?q=${query}`)
return res.json()
}
async function Results({ searchParams }) {
const { q } = await searchParams
return <ResultList results={await getResults(q)} />
}
export default function Page({ searchParams }) {
return (
<Suspense fallback={<Skeleton />}>
<Results searchParams={searchParams} />
</Suspense>
)
}// 之后 - 结果被缓存,并在解析 searchParams 后预取
import { Suspense } from 'react'
async function getResults(query: string) {
'use cache'
const res = await fetch(`https://api.example.com/search?q=${query}`)
return res.json()
}
async function Results({
searchParams,
}: Pick<PageProps<'/search'>, 'searchParams'>) {
const { q } = await searchParams
return <ResultList results={await getResults(q)} />
}
export default function Page({ searchParams }: PageProps<'/search'>) {
return (
<Suspense fallback={<Skeleton />}>
<Results searchParams={searchParams} />
</Suspense>
)
}// 之后 - 结果被缓存,并在解析 searchParams 后预取
import { Suspense } from 'react'
async function getResults(query) {
'use cache'
const res = await fetch(`https://api.example.com/search?q=${query}`)
return res.json()
}
async function Results({ searchParams }) {
const { q } = await searchParams
return <ResultList results={await getResults(q)} />
}
export default function Page({ searchParams }) {
return (
<Suspense fallback={<Skeleton />}>
<Results searchParams={searchParams} />
</Suspense>
)
}优化预取指南介绍了这种做法何时值得付出成本,以及运行时读取背后的缓存模式。