确保即时导航
了解如何组织应用以预取和预渲染更多内容,从而提供即时的页面加载和客户端导航。
本指南将带您了解即时导航、编写一个能够即时导航的路由、查看初始 UI 中的内容,以及通过端到端测试将该行为固定下来。
"instant" 的含义#
当用户点击的瞬间浏览器就能开始渲染新页面时,该导航就是即时的(instant):静态内容、缓存内容和回退内容会立即显示,而服务器则将其余内容流式传输到回退位置中。
小知识: 此定义假设缓存是热的。冷缓存仍然需要服务器计算一次缓存结果,因此首次导航到某个路由时可能仍需等待。
直接访问和客户端导航到同一路由可能产生不同的初始 UI。直接访问会以 HTML 形式获得静态外壳(static shell),通常来自 CDN。客户端导航只会重新渲染当前路由和目标路由共享的布局以下的部分,因此在该位置之上由 <Suspense> 边界定义的回退 UI 在过渡期间无法使用。
新页面是否即时显示,取决于共享布局下方的 <Suspense> 边界和缓存情况。
<details> <summary>为什么页面加载和客户端导航会产生不同的初始 UI</summary>
在页面加载时,整个页面从文档根节点开始渲染。每个组件都在服务器上运行,任何发生挂起(suspend)的内容都会被完整树中最近的 <Suspense> 边界捕获。
在 /store/shoes 和 /store/hats 之间的客户端导航中,只有 /store 布局以下的组件会重新渲染。根布局中的 <Suspense> 边界在页面加载时覆盖所有内容,但在此次导航中,它位于重新渲染范围之上,因此不会触发。
这也是客户端 Hook 行为不同的原因。useSearchParams() 在预渲染期间会挂起,因为搜索参数在构建时不可用。但在客户端导航时,路由器已经从 URL 中获取了参数,该 Hook 会同步解析。同一个组件在客户端导航时可以立即渲染,但在页面加载时却位于回退内容之后。
</details>
使用 prefetch={true} 时,按链接预取会在导航前解析链接的 URL 数据(searchParams 和 params)。首先要通过其 App Shell 使路由实现即时。如果没有 App Shell,按链接预取无法修复会阻塞的路由。相关模式请参阅优化预取。
快速开始#
要充分利用即时导航,需要启用缓存组件(Cache Components)和部分预取(Partial Prefetching),然后按照出现的验证错误进行处理:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfig为了帮助您使用智能体(agent)自动完成此过程,每个部分都有一个 Skill:next-cache-components-adoption 和 next-partial-prefetching-adoption。如果您想一次性启用所有功能,请给您的智能体以下提示词:
在此应用中采用缓存组件(Cache Components)和部分预取(Partial Prefetching),使其导航变为即时。每项迁移都有一个对应的 Skill。
1. 在做出任何更改之前,请用通俗易懂的语言向我解释什么是即时导航(Instant Navigation),以及采用它会带来哪些变化。
2. 安装所需的 Skill,然后在开发服务器运行的情况下,借助 next-dev-loop 和 agent-browser 随时验证你的更改:
- next-cache-components-adoption: https://www.skills.sh/vercel/next.js/next-cache-components-adoption
- next-partial-prefetching-adoption: https://www.skills.sh/vercel/next.js/next-partial-prefetching-adoption
- next-dev-loop: https://www.skills.sh/vercel/next.js/next-dev-loop
3. 每个 Skill 都会把决策留给我,例如每项工作的多少内容纳入每个拉取请求。请把这些问题提给我并等待我的回答,不要替我做决定。按照每个 Skill 规定的工作流程,先采用缓存组件,再采用部分预取。不要急于求成一个能通过的构建。
4. 每完成一个步骤,请向我展示一个表格,列出你涉及的路由以及每个路由的更改内容,并说明这些更改对应用意味着什么。请只关注结果,而非实现细节。本指南的其余部分介绍了这些迁移所使用的工具,逐步演示如何将一个会阻塞的导航变为即时导航,检查初始 UI 中包含哪些内容,并通过端到端测试将结果固定下来。
相关工具#
构建静态外壳#
借助缓存组件(Cache Components),缓存指令("use cache" 及其变体)为异步函数的结果指定生命周期,从而使 Next.js 能够将其纳入静态外壳。
小知识:
"use cache: private"是一个变体,用于缓存读取cookies()和headers()等运行时 API 的函数。结果仅在浏览器中缓存,而不在服务器上缓存。它不能成为静态外壳的一部分。 有关它如何与预取配合使用的说明,请参阅优化预取指南中的"use cache: private"。
<Suspense> 为树中读取未缓存数据或 cookies() 和 headers() 等运行时 API 的部分声明回退 UI;当内容解析完成时,内容会流式传输到回退位置中。
小知识: 回退内容可以访问
cookies()、headers()或完整 URL。在构建时,回退内容本身会挂起,因此需要树中更上层的<Suspense>边界。对于带有prefetch={true}的链接,按链接预取会在导航前使 URL 数据可用,因此回退内容可以成为预取 UI 的一部分。时间戳或数据获取等缓存值可以直接放在回退内容中。
Next.js 还可以为每个路由生成 App Shell,它在客户端导航期间渲染,同时其余内容进行流式传输。部分预取(Partial Prefetching)使用 App Shell 作为 <Link> 的默认预取内容。带有 prefetch={true} 的链接还可以解析依赖于该链接 URL 数据的缓存内容。
为链接预取 URL 数据#
在部分预取(Partial Prefetching)下,每个可见的 <Link> 默认都会预取目标页面的 App Shell。指向同一路由的链接共享一个 App Shell,而不是为每个链接触发单独的 App Shell 请求。
要为特定链接在预取外壳的同时预取页面内容,请设置 prefetch={true}:
<Link href="/checkout" prefetch>
Checkout
</Link>启用部分预取后,prefetch={true} 还会让该链接选择加入按链接预取,从而在点击之前解析按链接的 URL 数据(params、searchParams 和完整 URL)。
验证即时导航#
默认情况下(validationLevel: 'warning'),缓存组件(Cache Components)应用会在开发环境中验证每个 Page 和 Default 片段。验证会揭示哪些因素会阻止进入某片段的导航成为即时导航——哪些导航会阻塞、哪里缺少 <Suspense> 边界,以及哪些数据未经缓存就到达用户。
要退出自动验证、仅验证显式导出 instant 的片段,请将 validationLevel 设置为 'manual-warning':
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
experimental: {
instantInsights: {
validationLevel: 'manual-warning',
},
},
}
export default nextConfig<details> <summary>验证如何模拟不同的导航</summary>
对于每个经过验证的路由,Next.js 会在路由层级的不同位置检查初始页面加载和客户端导航。
对于像 /shop/[slug] 这样的路由,验证会检查:
- 页面加载:完整树从根节点开始渲染。根布局的
<Suspense>捕获所有内容。 - 客户端导航(例如从
/shop/shoes到/shop/hats):/shop布局已经挂载,只有其下方的页面重新渲染。根布局中的<Suspense>边界不覆盖此次导航。
每种情况都会独立验证。覆盖某一条导航路径的 <Suspense> 边界可能不会覆盖另一条路径。这就是为什么一个页面可能通过页面加载检查,但在客户端导航时失败,也是为什么随着路由数量增加,手动发现这些问题变得困难。
</details>
在 CI 中测试#
@next/playwright 包提供了一个 instant() 辅助函数,可将断言限定在导航时立即可用的 UI 上,从而在 CI 中发现回归问题。相关模式请参阅通过 e2e 测试防止回归。
检查加载状态#
Next.js DevTools 中的 Navigation Inspector 会将页面冻结在初始加载状态,在直接访问时显示静态外壳,在客户端导航时显示预取的目标页面。使用该检查器可以查看外壳中有多少有意义的内容。
将其与 React DevTools 的 Suspense 面板配合使用,可以准确查看哪个边界覆盖了页面的哪一部分。相关工作流程请参阅使用 Next.js DevTools 可视化加载状态。
有关减少回退覆盖范围、让更多完整 UI 立即可用的模式,请参阅优化静态外壳。
一个即时导航的页面#
要了解这些基础功能的实际运用,可以看一个简单的商店应用。每个商品都有自己的页面 /store/[slug],可从首页和其他商品页面访问。目标是让进入商品页面以及在商品页面之间导航都是即时的。
商品页面获取两项数据:商品详情(名称、价格)和实时库存。
- 没有
generateStaticParams,这意味着slug仅在请求时可知 - 两个组件都等待
params以获取slug,这会发生挂起。每个组件都有自己的<Suspense>边界 - 商品信息很少变化,使用缓存函数从数据库查询
- 库存必须在每次请求时都是最新的。数据库查询位于
<Suspense>边界内
import { Suspense } from 'react'
import { db } from '@/lib/db'
export default function ProductPage(props: PageProps<'/store/[slug]'>) {
return (
<div>
<Suspense fallback={<p>Loading product...</p>}>
<ProductInfo params={props.params} />
</Suspense>
<Suspense fallback={<p>Checking availability...</p>}>
<Inventory params={props.params} />
</Suspense>
</div>
)
}
type Params = PageProps<'/store/[slug]'>['params']
async function ProductInfo({ params }: { params: Params }) {
const { slug } = await params
const product = await getProduct(slug)
return (
<>
<h1>{product.name}</h1>
<p>${product.price}</p>
</>
)
}
async function getProduct(slug: string) {
'use cache'
return db.products.findBySlug(slug)
}
async function Inventory({ params }: { params: Params }) {
const { slug } = await params
const item = await db.inventory.findBySlug(slug)
return <p>{item.count} in stock</p>
}缓存组件(Cache Components)会在开发环境中自动验证此路由。如果有内容会阻塞导航,开发浮层会显示一条 blocking-route(阻塞路由)洞察,指出有问题的组件并指向以下修复方法:
小知识: 每张修复卡片都链接到包含模式、代码示例和权衡取舍的详细说明。点击卡片可深入了解,或使用 Copy prompt(复制提示词)将修复交给您的智能体。相关循环流程请参阅 AI 工作流。
验证会在每次页面加载时使用来自浏览器的真实请求运行,因此像 [slug] 这样的动态参数会在您导航时根据实际值进行检查。
客户端组件页面#
软导航进入顶部带有 "use client" 的页面时,其行为类似于单页应用过渡,导航时没有服务器渲染,因此是即时的。开发浮层的修复卡片中不包含此方式,因为与推荐的做法(将页面保持在服务器组件模型中)相比,它影响更大。当页面完全交互式且必须是客户端组件时,才使用 "use client"。
小知识:
"use client"不会跳过对静态外壳的验证。像useSearchParams()这样的 Hook 仍然需要<Suspense>边界。
使用 Next.js DevTools 可视化加载状态#
在开发路由时,Next.js DevTools 可以让您看到用户在页面加载和客户端导航时、动态数据流入之前所看到的内容。使用它可验证加载状态是否正确、确认期望的内容是否立即出现,并迭代调整 <Suspense> 边界的位置。
React DevTools Suspense 面板对此进行了补充:它列出了树中的 <Suspense> 边界,并允许您在每个边界的回退状态和已解析状态之间切换,从而准确查看哪个边界覆盖了页面的哪一部分。
当启用缓存组件(Cache Components)时,Navigation Inspector 可用:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig打开 Next.js DevTools 并选择 Navigation Inspector,然后切换 Pause on navigations(导航时暂停)。面板显示 Awaiting navigation...(等待导航...)。开启该开关后,下一次刷新或链接点击会冻结页面,以便您检查外壳。
刷新商品页面。检查器显示 Loading shell(加载外壳),标记为 Page load(页面加载)并带有目标 URL。两个回退内容都会出现:"Loading product..." 和 "Checking availability...". 此路由没有 generateStaticParams,因此即使重复访问,静态外壳也不包含商品详情。
<div style={{
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
gap: '0.5rem',}}
<span style={{ fontSize: '0.875rem', opacity: 0.7 }}>
页面刷新后。</span> </div>
点击 Resume(继续)以查看商品详情和库存。
现在从 /store/shoes 点击一个带有 prefetch={true} 的链接前往 /store/hats。检查器显示 Loading shell,标记为 Client nav(客户端导航),并带有源 URL 和目标 URL。启用部分预取后,该链接已经获取了商品名称和价格。库存仍显示 "Checking availability..."。
<div style={{
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
gap: '0.5rem',}}
<span style={{ fontSize: '0.875rem', opacity: 0.7 }}>
客户端导航后。</span> </div>
检查完加载状态后,关闭 Pause on navigations 开关。只要开关处于开启状态,每次导航都会暂停。
小知识: 页面加载和客户端导航可能产生不同的外壳。像
useSearchParams这样的客户端 Hook 在页面加载时会挂起(搜索参数在构建时未知),但在客户端导航时会同步解析(路由器已经拥有这些参数)。
使用浏览器自动化检查加载状态#
启用缓存组件(Cache Components)后,浏览器工具可以在运行中的 next dev 服务器上暂停导航。打开 /store/shoes 并在浏览器中设置此 cookie:
document.cookie = 'next-instant-navigation-testing=1; path=/'点击指向 /store/hats 的链接并等待目标 URL。Next.js 会等待链接的预取完成。在此示例中,默认的 <Link> 会显示两个回退内容。启用 prefetch={true} 和部分预取后,商品名称和价格会与 "Checking availability..." 一起显示。
要检查同一 URL 的静态外壳,请在设置 cookie 的情况下重新加载。
要恢复,请清除 cookie,即使检查失败也是如此:
document.cookie = 'next-instant-navigation-testing=; path=/; max-age=0'通过 e2e 测试防止回归#
验证会在开发期间发现结构性问题,但随着代码库增长,结构检查只能告诉您外壳是否存在,无法告诉您其中是否包含正确的内容。E2E 测试弥补了这一空白:它们对用户导航完成时实际看到的内容进行断言,从而在回归问题发布前将其捕获。
使用 @next/playwright 中的 instant() 来测试上面的商品路由。
路由可以通过两种方式到达,而 <Suspense> 边界可能覆盖其中一种而不覆盖另一种:
- 初始页面加载:使用
page.goto()测试来自文档响应的静态 UI。 - 客户端导航:点击
<Link>以测试目标页面的预取 UI。按链接预取可以向此 UI 添加特定于请求的内容。
import { test, expect } from '@playwright/test'
import { instant } from '@next/playwright'
test.describe('Product page (/store/[slug])', () => {
test('is instant on an initial page load', async ({ page, baseURL }) => {
await instant(
page,
async () => {
await page.goto('/store/hats')
await expect(
page.getByText('Loading product...').filter({ visible: true })
).toBeVisible()
await expect(
page.getByText('In stock').filter({ visible: true })
).toHaveCount(0)
},
{ baseURL }
)
await expect(page.getByRole('heading', { level: 1 })).toContainText(
'Baseball Cap'
)
await expect(
page.getByText('In stock').filter({ visible: true })
).toBeVisible()
})
test('is instant on a client navigation', async ({ page }) => {
await page.goto('/store/shoes')
await instant(page, async () => {
await page
.locator('a[href="/store/hats"]')
.filter({ visible: true })
.click()
await page.waitForURL((url) => url.pathname === '/store/hats')
await expect(page.getByRole('heading', { level: 1 })).toContainText(
'Baseball Cap'
)
await expect(
page.getByText('In stock').filter({ visible: true })
).toHaveCount(0)
})
await expect(
page.getByText('In stock').filter({ visible: true })
).toBeVisible()
})
})示例路由没有 generateStaticParams,因此其商品标题位于初始静态外壳之外。请在初始加载范围内检查商品回退内容,并在其完成后检查标题。在客户端导航中,按链接预取使商品标题在范围内可用。
有关安装、生产环境设置和搜索参数更新,请参阅 Playwright 指南。
修复会阻塞的导航#
考虑另一个路由 /products/[slug],它从公共 API 获取商品数据并同时显示一个精选列表:
export default async function ProductPage(
props: PageProps<'/products/[slug]'>
) {
const featured = await getFeatured()
const { slug } = await props.params
const res = await fetch(`https://next-recipe-api.vercel.dev/products/${slug}`)
const product = await res.json()
return (
<div>
<FeaturedSection items={featured} />
<h1>{product.name}</h1>
<p>${product.price}</p>
<p>{product.description}</p>
</div>
)
}
async function getFeatured() {
const res = await fetch('https://next-recipe-api.vercel.dev/products?limit=3')
return res.json()
}有两个 fetch() 调用在顶层阻塞:一个是未缓存的精选列表获取,另一个是按 slug 的商品获取(它还等待 params)。两者都会显示为即时导航验证错误,一次一个。
第 1 步:将依赖 slug 的工作移入 Suspense#
验证首先显示按 slug 的商品获取问题。
<div style={{
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
gap: '0.5rem',}}
</div>
将依赖 slug 的工作提取到一个子组件中,并用 <Suspense> 包裹它:
import { Suspense } from 'react'
async function ProductInfo({ params }: { params: Promise<{ slug: string }> }) {
const { slug } = await params
const res = await fetch(`https://next-recipe-api.vercel.dev/products/${slug}`)
const product = await res.json()
return (
<>
<h1>{product.name}</h1>
<p>${product.price}</p>
<p>{product.description}</p>
</>
)
}
export default async function ProductPage(
props: PageProps<'/products/[slug]'>
) {
const featured = await getFeatured()
return (
<div>
<FeaturedSection items={featured} />
<Suspense fallback={<p>Loading product...</p>}>
<ProductInfo params={props.params} />
</Suspense>
</div>
)
}现在 await props.params 和商品获取会一起挂起。商品获取错误消失,验证继续进行下一个阻塞项。
第 2 步:缓存精选列表的获取#
现在验证会针对 getFeatured() 报错。
<div style={{
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
gap: '0.5rem',}}
</div>
在获取函数中添加 "use cache" 指令:
async function getFeatured() {
'use cache'
const res = await fetch('https://next-recipe-api.vercel.dev/products?limit=3')
return res.json()
}结果在 fetch 层面被缓存。精选列表随 App Shell 一起提供。
小知识: 在无服务器(serverless)部署中,使用
"use cache"的内存缓存不会跨实例持久保存。请考虑使用"use cache: remote"进行持久化缓存。
验证通过。打开 DevTools 并尝试客户端导航。精选区域立即出现,"Loading product..." 显示商品详情将流式传输到的位置。
迭代优化加载状态#
验证通过意味着导航是即时的,但不意味着加载状态良好。放在树中较高位置的 <Suspense> 边界(例如包裹整个页面)可能满足验证要求,但每次导航时它会用单个回退内容替换页面的大部分内容。
最佳的加载状态会尽可能多地保持真实的缓存内容可见,仅在数据实际传输中的地方显示回退内容。一个商品页面如果保持页眉、图片和描述可见,仅将价格和库存情况置于回退内容之后,即使总加载时间相同,也会比整页骨架屏感觉更快。
使用 DevTools 查看用户看到的内容,或参阅 AI 工作流 了解如何使用智能体自动化该循环。
AI 工作流#
总体而言,智能体按如下方式优化单个导航:
- 观察:阅读验证洞察,选择应立即显示的确切导航和 UI。
- 测试:确认目标 UI 正常渲染,然后编写
instant()测试并验证在更改路由之前该测试会失败。 - 修复:验证错误会指出具体的组件并建议修复方法(
use cache或<Suspense>)。智能体应用修复并重新运行验证。 - 验证:针对类似生产环境的构建运行测试,并将通过的测试保留为回归防护。
智能体不需要理解完整的缓存模型,只需按照洞察和错误提示操作,直到它们消失即可。不过,它确实需要您针对应用的意图。告诉它哪些内容应立即显示、哪些内容可以流式传输、哪些内容必须保持最新。当缓存决策不明确时,将数据保持在 <Suspense> 之后以保持最新,而不要猜测缓存生命周期。
对于迭代优化加载状态,类似"最大化我的内容,减少需要放在加载指示器之后的内容量"这样的提示词很适合用于下移边界。
处理缓存组件(Cache Components)路由的智能体通常会使用三个手段:
- 下移:将 I/O 提取到由 Suspense 包裹的子组件中,使父组件保持静态,静态的兄弟组件进入外壳。
- 缓存:将
'use cache'与cacheLife结合使用,以指定新鲜度配置。 - 按链接预取(仅导航时):当路由读取 URL 数据(
searchParams或params)时,让它选择加入按链接预取,以便框架在链接预取时解析这些数据。来自cookies()或headers()的会话数据即使不使用它也会进入 App Shell。
每次重构都应配以前后截图,以验证更改确实生效。看起来相同的截图意味着重构没有起作用。
要让智能体看到其更改实际渲染出的内容,可将其与 agent-browser 结合使用。启用 React DevTools 后,它会报告组件树以及哪些 <Suspense> 边界仍处于挂起状态,这样智能体可以进行更改、快照外壳、检查已生成的内容并进行调整。相关设置请参阅 AI agents 指南中的运行时可见性。
next-cache-components-optimizer Skill 封装了这个循环。它确认目标 UI 正常渲染,编写一个在修复前会失败的 instant() 测试,然后针对类似生产环境的构建使其通过,并将其作为回归防护发布。可将它用于初始加载(硬导航)、客户端导航(软导航)或两者。
选择退出#
并非每个布局或页面都能或都应该即时导航。当结构性修复不值得投入,或某个路由不是即时导航的优先对象时,可以在两种范围之一细化验证。
开发浮层会在每条洞察旁边将此显示为 Block(阻塞)修复:
在页面或布局文件中设置 instant = false。这会让该片段退出验证反馈。如果其结构支持,该片段仍可能实现即时导航;框架只是不会为它显示洞察。其下同级片段之间的导航仍会经过验证。
export const instant = false在 /dashboard/layout.tsx 上设置 false 后,验证不再标记从外部进入 /dashboard 的导航;/dashboard/a 和 /dashboard/b 之间的导航仍会检查。
子页面默认仍会经过验证。要让子页面退出验证,请从该页面导出 instant = false。如果它是客户端组件,请使用服务器组件页面包装器。
对于选择退出的片段,导航会在服务器上阻塞。如果内容依赖 cookie 或 header,但具有已知的缓存生命周期,则可以使用 use cache: private 缓存它,让 App Shell 在点击之前就携带它,而不必退出验证,前提是其 stale 时间至少为 5 分钟。
下一步#
- 采用部分预取(Adopting Partial Prefetching):了解推荐的
<Link>默认设置和逐步采用路径 instantAPI 参考:了解完整配置- 优化预取:当路由的某些部分依赖 URL 数据(
searchParams或params)并应在导航前解析时使用 - 缓存:了解
use cache、Suspense 和部分预渲染的背景知识 - 重新验证:了解如何使用
cacheLife和updateTag使缓存数据过期