NNext.js 中文网 GitHub

迁移到 Cache Components

了解如何在 Next.js 中从路由段配置迁移到 Cache Components。

当启用 Cache Components 时,诸如 dynamic、revalidate 和 fetchCache 之类的路由段配置将被 use cache 和 cacheLife 取代。

此迁移由即时导航验证驱动。启用 Cache Components 后,Next.js 会在开发环境中验证导航到每个路由时是否能即时渲染,并将阻塞它的代码作为错误或洞察(insight)呈现出来。

使用采用技能(推荐)#

next-cache-components-adoption 技能通过编码代理(coding agent)推动此迁移,一次一个功能,并在每个功能节点进行检查。它支持两种模式:

  • 增量式。 打开一个机械式的 PR,让每个路由都退出验证,然后将每个功能作为后续 PR 发布。这自动化了下面的增量采用流程。
  • 直接式。 在一个分支上就地采用所有路由。

安装该技能:

Terminal
npx skills add vercel/next.js --skill next-cache-components-adoption

然后给代理这个提示:

prompt
使用 next-cache-components-adoption 技能在本项目中采用 Cache Components。

或者手动迁移#

手动迁移现有应用需要按顺序执行以下几个步骤:

  1. 在 next.config.ts 中启用 Cache Components。
  2. 决定你的方法:立即转换所有路由,或者先让路由退出验证,再逐步采用,一次转换一个。
  3. 跟进其呈现的验证错误和洞察,将每个路由段配置替换为对应的 Cache Components 配置,并使用 use cache 缓存未缓存的数据,或将运行时数据包裹在 <Suspense> 中。下面的各小节分别介绍了每种配置和 API。

你现有的 fetch 和 unstable_cache 缓存仍然有效。迁移 unstable_cache 是可选的,可以稍后进行。

某些方面有其自身的步骤:

以下各小节介绍了每种配置和 API,以及在 Cache Components 下应如何处理它们。

启用 Cache Components#

Cache Components 需要 Next.js 16。如果你使用的是 Next.js 15 或更早版本,请先按照 version 16 升级指南进行升级。如果你从更旧的版本升级而来,请先完成升级指南中的步骤以达到版本 16,然后再继续。

然后在 next.config.ts 中启用 cacheComponents 标志:

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

小知识: 如果你之前使用 experimental.dynamicIO 或 experimental.useCache,cacheComponents 已取代它们。请参阅 version 16 升级指南。

启用该标志后,仍然导出 dynamic、revalidate 或 fetchCache 的路由段将报错。请先替换这些配置。下面的各小节说明了每种配置应如何处理。

退出验证#

验证洞察或错误会告诉你某个路由无法即时渲染。按照建议来解决它:使用 use cache 缓存数据,或将其包裹在 <Suspense> 中。如果你尚未准备好处理它,请在引发该问题的路由段(布局、页面或并行插槽)上将 instant 配置设为 false,稍后再回来处理。

app/dashboard/layout.tsx
export const instant = false

小知识:instant = false 将某个路由段标记为允许阻塞。它不会强制路由变为动态,因此真正可预渲染的路由仍会提供静态外壳。它也不会清除同步 IO 构建错误:诸如 new Date()、Math.random() 和 crypto.randomUUID() 之类的调用仍会导致预渲染失败。请参阅增量采用。

增量采用#

你不必一次迁移所有路由。instant = false 让你先让整个应用能够构建并运行,然后再一次转换一个路由:

  1. 启用该标志并迁移每个路由段配置。 按照下面相关章节处理 dynamic = "force-dynamic"、dynamic = "force-static"、dynamic = "error"、revalidate 和 fetchCache。对于带有动态参数的路由,还需遵循 generateStaticParams 指南。仍能即时渲染的路由无需进一步处理。
  2. 让尚未准备好的路由退出验证。 在出现洞察或错误的地方,在引发它的路由段上设置 instant = false。若要一次性对整个应用执行此操作,请运行 cache-components-instant-false codemod,它会为每个尚未声明 instant 的 page、layout 和 default 添加退出配置:

``bash filename="Terminal" npx @next/codemod@canary cache-components-instant-false ./app ``

> 小知识:在 src/ 项目中传入 ./src/app。路径错误时命令会报告 0 ok 而不是失败,因此请检查文件数量。

应用会继续构建和提供服务,现在对已退出的路由推迟了验证。

  1. 修复同步 IO。它无法被推迟。 在预渲染期间调用 new Date()、Date.now()、Math.random() 和 crypto.randomUUID() 等会抛出 instant = false 无法清除的构建错误,因此使用它们的路由在完成修复前无法构建,无论是否退出。将该调用移出预渲染外壳,使其在请求时运行:将需要它的部分包裹在 <Suspense> 中,并在调用前使用 connection(),或将其移入 Client Component。
  2. 一次转换一个路由。 从某个路由中移除 instant = false,然后通过使用 use cache 缓存数据或将运行时数据包裹在 <Suspense> 中来解决其洞察。重复此过程,直到没有任何路由退出。

跟进验证#

Cache Components 会在开发环境中验证你的路由,并在开发覆盖层中呈现错误和洞察。有些如下所示,会指出受影响的组件并给出修复建议:

每张卡片都可以点击,会打开一个包含模式、代码示例和权衡取舍的页面。逐一处理洞察和错误,直到它们消失。有关完整的验证工作流程、DevTools 和 CI 测试,请参阅即时导航指南。

洞察不会出现在 HTTP 响应中。在开发环境中,存在问题的路由仍会返回 200 和渲染后的 HTML。洞察只会出现在开发覆盖层、开发服务器日志或 MCP get_errors 工具中。要查看它们,请阅读覆盖层(或查询 MCP)。

dynamic = "force-dynamic"#

移除该配置。 在没有 Cache Components 的情况下,dynamic = 'force-dynamic' 会为每个请求渲染整个路由,并使其 fetch 请求不被缓存。使用 Cache Components 时,未缓存的数据和请求时 API 本身就在请求时运行。Next.js 会预渲染它们周围的任何静态或已缓存的 UI。

移除该配置后,请跟进出现的任何验证错误或洞察。

app/page.tsx
// 之前
export const dynamic = 'force-dynamic'

export default function Page() {
  return <div>...</div>
}
app/page.js
// 之前
export const dynamic = 'force-dynamic'

export default function Page() {
  return <div>...</div>
}
app/page.tsx
// 之后
export default function Page() {
  return <div>...</div>
}
app/page.js
// 之后
export default function Page() {
  return <div>...</div>
}

dynamic = "force-static"#

移除该配置,然后使其缓存显式化。 在没有 Cache Components 的情况下,dynamic = 'force-static' 会强制路由预渲染、缓存其数据,并使 cookies()、headers() 和 useSearchParams() 返回空值。

使用 use cache 和合适的 cacheLife 缓存应被复用的数据。移除该配置后,请求时 API 会读取实际的请求值。如果路由必须保持完全预渲染,请移除这些依赖。

app/page.tsx
// 之前
export const dynamic = 'force-static'

export default async function Page() {
  const data = await fetch('https://api.example.com/data')
  return <div>...</div>
}
app/page.js
// 之前
export const dynamic = 'force-static'

export default async function Page() {
  const data = await fetch('https://api.example.com/data')
  return <div>...</div>
}
app/page.tsx
import { cacheLife } from 'next/cache'

// 之后
export default async function Page() {
  'use cache'
  cacheLife('max')
  const data = await fetch('https://api.example.com/data')
  return <div>...</div>
}
app/page.js
import { cacheLife } from 'next/cache'

// 之后
export default async function Page() {
  'use cache'
  cacheLife('max')
  const data = await fetch('https://api.example.com/data')
  return <div>...</div>
}

强制静态输出#

小知识:ensureStatic 在 Next.js 16.4 及更高版本中可用。此步骤是可选的。仅当迁移后路由仍有静态输出要求时才添加它。

要要求路由完全静态,请在迁移其缓存后添加 ensureStatic = 'navigation':

app/page.tsx
export const ensureStatic = 'navigation'
app/page.js
export const ensureStatic = 'navigation'

与 dynamic = 'force-static' 不同,ensureStatic 不会使请求时 API 返回空值。如果特定于请求的服务端工作阻止了路由的预渲染,它会报告错误。如果只需保持 App Shell 或逐链接预取为静态,请选择限制较宽松的级别。请参阅保持页面为静态。

dynamic = "error"#

移除该配置。 在没有 Cache Components 的情况下,dynamic = 'error' 要求路由进行预渲染,并默认将 fetch 请求视为已缓存。只有当未缓存的数据或请求时 API 阻止预渲染时,它才会抛出错误。

移除该配置后,fetch 不再继承该缓存默认值。为了保留路由现有的缓存行为,请将这些请求包裹在 use cache 中,并使用 cacheLife 设置其生命周期。如果路由并未依赖该默认值,则无需替换。

强制静态验证#

小知识:ensureStatic 在 Next.js 16.4 及更高版本中可用。此步骤是可选的。仅当迁移后路由仍有静态输出要求时才添加它。

要要求路由完全静态,请在明确路由的缓存后添加 ensureStatic = 'navigation':

app/page.tsx
export const ensureStatic = 'navigation'
app/page.js
export const ensureStatic = 'navigation'

当只需保持 App Shell 或逐链接预取为静态时,请使用限制较宽松的级别。请参阅保持页面为静态以了解如何选择级别。

revalidate#

将大于零的重新验证时间替换为 cacheLife。 在没有 Cache Components 的情况下,revalidate 为整个路由设置默认的重新验证时间。使用 Cache Components 时,请将 use cache 放在应被缓存的数据或 UI 周围,然后使用 cacheLife 设置其生命周期。

app/page.tsx
// 之前
export const revalidate = 3600 // 1 小时

export default async function Page() {
  return <div>...</div>
}
app/page.js
// 之前
export const revalidate = 3600 // 1 小时

export default async function Page() {
  return <div>...</div>
}
app/page.tsx
// 之后
import { cacheLife } from 'next/cache'

export default async function Page() {
  'use cache'
  cacheLife('hours')
  return <div>...</div>
}
app/page.js
// 之后
import { cacheLife } from 'next/cache'

export default async function Page() {
  'use cache'
  cacheLife('hours')
  return <div>...</div>
}

小知识:如果你的 revalidate 值与内置的 cacheLife 配置('seconds'、'minutes'、'hours'、'days'、'weeks'、'max')都不匹配,请选择最接近的一个,或定义一个自定义配置以符合你的约定。当内置配置的时间设置不符合应用的缓存需求时,你还可以重新定义内置配置(包括 default)。

对于 revalidate = 0,请移除该配置。使用 Cache Components 时,未缓存的数据本身就在请求时运行。当数据必须为每个请求运行时,请将其保持在 use cache 作用域之外。

fetchCache#

移除该配置,并在数据源处设置缓存。 在没有 Cache Components 的情况下,fetchCache 会更改或限制路由中每个 fetch 请求的 cache 选项。使用 Cache Components 时,除非在 use cache 作用域内运行,否则 fetch 不会被缓存。

对于 default-cache、only-cache 或 force-cache,请将应保持缓存的数据包裹在 use cache 中。对于 default-no-store、only-no-store 或 force-no-store,请将数据留在缓存作用域之外。如果 force-no-store 之前覆盖了显式的缓存选项,也请移除该选项。

app/page.tsx
// 之前
export const fetchCache = 'force-cache'
app/page.js
// 之前
export const fetchCache = 'force-cache'
app/page.tsx
// 之后
export default async function Page() {
  'use cache'
  // 此处的所有 fetch 都会被缓存
  return <div>...</div>
}
app/page.js
// 之后
export default async function Page() {
  'use cache'
  // 此处的所有 fetch 都会被缓存
  return <div>...</div>
}

fetch 缓存选项#

将 cache 和 next 选项迁移到 use cache。

在没有 Cache Components 的情况下,你使用 cache: 'force-cache' 缓存请求,并使用 next: { revalidate, tags } 对其进行调整。

使用 Cache Components 时,请将 fetch 包裹在 use cache 函数中。该作用域内的 fetch 会被自动缓存,revalidate 和 tags 分别变为 cacheLife 和 cacheTag。

app/page.tsx
// 之前
export default async function Page() {
  const res = await fetch('https://api.example.com/data', {
    cache: 'force-cache',
    next: { revalidate: 3600, tags: ['data'] },
  })
  const data = await res.json()
  return <div>...</div>
}
app/page.js
// 之前
export default async function Page() {
  const res = await fetch('https://api.example.com/data', {
    cache: 'force-cache',
    next: { revalidate: 3600, tags: ['data'] },
  })
  const data = await res.json()
  return <div>...</div>
}
app/page.tsx
// 之后
import { cacheLife, cacheTag } from 'next/cache'

async function getData() {
  'use cache'
  cacheLife('hours')
  cacheTag('data')
  const res = await fetch('https://api.example.com/data')
  return res.json()
}

export default async function Page() {
  const data = await getData()
  return <div>...</div>
}
app/page.js
// 之后
import { cacheLife, cacheTag } from 'next/cache'

async function getData() {
  'use cache'
  cacheLife('hours')
  cacheTag('data')
  const res = await fetch('https://api.example.com/data')
  return res.json()
}

export default async function Page() {
  const data = await getData()
  return <div>...</div>
}

注意持久性方面的差异。fetch 数据缓存会跨部署和跨无服务器实例持久化缓存的响应。

use cache 默认使用内存存储,因此当无服务器实例被销毁时,其条目会被丢弃,并且其作用域仅限于单次部署。使用 use cache: remote 或 cache handler 可以获得在实例销毁后仍然存在的存储。即使使用持久化存储,也应预期缓存值会在新部署后重新计算。

unstable_cache#

无需更改。

unstable_cache 继续与 Cache Components 一起工作。你可以保留原样,稍后再迁移。

如果你选择迁移它,请将被包裹的函数转换为带有 'use cache' 指令的函数。缓存键会根据参数自动派生,因此不再需要 key-parts 数组,而 options 对象对应于 cacheLife 和 cacheTag。

app/lib/data.ts
// 之前
import { unstable_cache } from 'next/cache'
import { db } from '@/lib/db'

export const getUser = unstable_cache(
  async (id: string) => {
    return db.query.users.findFirst({ where: eq(users.id, id) })
  },
  ['user'], // 缓存键前缀
  { tags: ['users'], revalidate: 3600 }
)
app/lib/data.js
// 之前
import { unstable_cache } from 'next/cache'
import { db } from '@/lib/db'

export const getUser = unstable_cache(
  async (id) => {
    return db.query.users.findFirst({ where: eq(users.id, id) })
  },
  ['user'], // 缓存键前缀
  { tags: ['users'], revalidate: 3600 }
)
app/lib/data.ts
// 之后
import { cacheLife, cacheTag } from 'next/cache'
import { db } from '@/lib/db'

export async function getUser(id: string) {
  'use cache'
  cacheLife('hours')
  cacheTag('users')
  return db.query.users.findFirst({ where: eq(users.id, id) })
}
app/lib/data.js
// 之后
import { cacheLife, cacheTag } from 'next/cache'
import { db } from '@/lib/db'

export async function getUser(id) {
  'use cache'
  cacheLife('hours')
  cacheTag('users')
  return db.query.users.findFirst({ where: eq(users.id, id) })
}

与 fetch 数据缓存一样,unstable_cache 会跨部署和无服务器实例持久化缓存值,而 use cache 不会。有关存储的详细信息,请参阅上文的 fetch 缓存选项。

React.cache#

通常无需更改。 React.cache 会继续在 React 渲染中对匹配的调用进行去重。

但是,每个 Cache Function 都有独立的 React 缓存作用域。来自不同 Cache Function 的调用不会共享 React.cache 结果,例如当一个 Cache Function 预加载数据而另一个消费它时。

当辅助函数读取请求数据,且匹配的调用需要跨 Cache Function 作用域共享工作时,请将 React 包装器替换为 'use cache: private'。如果该函数只需要请求作用域内的去重,请使用 cacheLife({ stale: Infinity }),以免降低路由的 stale 时间。私有 Cache Function 的结果不会在生产请求之间存储在服务端缓存中。

按需重新验证(revalidateTag、revalidatePath、updateTag)#

按需失效仍然通过为缓存数据打标签并在事件发生后使其过期来工作。请在 use cache 函数中使用 cacheTag 为数据打标签,而不是使用 fetch 的 next.tags 选项,然后根据所需行为选择失效 API:

  • updateTag:适用于用户必须立即看到结果的变更操作(read-your-own-writes,读己之写)。从 Server Action 调用时,它会使标签过期,以便下一个请求等待新数据,而不是提供过时的内容。
  • revalidateTag:用于 stale-while-revalidate(后台刷新时返回旧内容)。必须将缓存配置作为第二个参数传入,例如使用 'max' 在后台刷新时提供缓存数据。可在 Server Actions 和 Route Handlers 中使用。
  • revalidatePath:与之前的缓存模型相比没有变化。

updateTag 并非 Cache Components 独有(它也适用于之前的缓存模型),但迁移是采用它的好时机。在 Server Action 中执行变更后,当用户应立即看到自己的更改时,就使用它。

app/actions.ts
'use server'
import { updateTag } from 'next/cache'

export async function createPost(formData: FormData) {
  // 创建帖子,然后在下一个请求中立即显示
  updateTag('posts')
}
app/actions.js
'use server'
import { updateTag } from 'next/cache'

export async function createPost(formData) {
  // 创建帖子,然后在下一个请求中立即显示
  updateTag('posts')
}

小知识: updateTag 只能从 Server Action 中调用;在其他地方调用会抛出异常。在 Route Handlers 或 webhook 中,请改用 revalidateTag 并传入缓存配置。

将 'max' 作为第二个参数传递给 revalidateTag,以使用 stale-while-revalidate 语义使标签过期:

app/api/webhook/route.ts
// 之前
import { revalidateTag } from 'next/cache'

export async function POST() {
  revalidateTag('posts')
  return Response.json({ ok: true })
}
app/api/webhook/route.js
// 之前
import { revalidateTag } from 'next/cache'

export async function POST() {
  revalidateTag('posts')
  return Response.json({ ok: true })
}
app/api/webhook/route.ts
// 之后——传入缓存配置
import { revalidateTag } from 'next/cache'

export async function POST() {
  revalidateTag('posts', 'max')
  return Response.json({ ok: true })
}
app/api/webhook/route.js
// 之后——传入缓存配置
import { revalidateTag } from 'next/cache'

export async function POST() {
  revalidateTag('posts', 'max')
  return Response.json({ ok: true })
}

unstable_noStore#

不再需要。 unstable_noStore(noStore())用于让组件退出缓存。使用 Cache Components 时,除非你添加 use cache,否则不会缓存任何内容,因此你可以移除它。如果某个组件必须在请求时运行,请在执行工作前调用 connection(),并将其包裹在 <Suspense> 中。

app/page.tsx
// 之前
import { unstable_noStore as noStore } from 'next/cache'

export default async function Page() {
  noStore()
  const data = await db.query('...')
  return <div>...</div>
}
app/page.js
// 之前
import { unstable_noStore as noStore } from 'next/cache'

export default async function Page() {
  noStore()
  const data = await db.query('...')
  return <div>...</div>
}
app/page.tsx
// 之后——默认不缓存,只需移除 noStore()
export default async function Page() {
  const data = await db.query('...')
  return <div>...</div>
}
app/page.js
// 之后——默认不缓存,只需移除 noStore()
export default async function Page() {
  const data = await db.query('...')
  return <div>...</div>
}

generateStaticParams 与 dynamicParams#

Cache Components 改变了动态路由处理参数的方式。

generateStaticParams 必须返回至少一个参数#

返回空数组现在会报错。 在没有 Cache Components 的情况下,返回 [] 会将每条路径推迟到首次运行时访问时处理。使用 Cache Components 时,generateStaticParams 必须返回至少一个参数,以便 Next.js 预渲染路由并验证其生成非空的静态外壳。返回空数组会引发 empty-generate-static-params。

保留 generateStaticParams 并返回至少一个真实参数。移除该导出会使路由退出 ISR,因此 Next.js 会在每个请求上渲染它,即使它使用 use cache 来处理数据。请阅读 ISR 与 Cache Components以了解 generateStaticParams 如何预渲染动态路由,以及未列出的路径如何处理。

app/blog/[slug]/page.tsx
// 之前——将所有路径推迟到运行时
export async function generateStaticParams() {
  return []
}
app/blog/[slug]/page.js
// 之前——将所有路径推迟到运行时
export async function generateStaticParams() {
  return []
}
app/blog/[slug]/page.tsx
// 之后——返回至少一个参数以进行预渲染
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
  return posts.slice(0, 1).map((post) => ({ slug: post.slug }))
}
app/blog/[slug]/page.js
// 之后——返回至少一个参数以进行预渲染
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
  return posts.slice(0, 1).map((post) => ({ slug: post.slug }))
}

你未返回的路径仍会在请求时提供服务。

小知识: 当你使用 generateStaticParams 而未启用 Partial Prefetching 时,请在 <Suspense> 外部等待 params,以保留未列出路径的 ISR。要在未列出路径渲染时提供回退内容,请启用 Partial Prefetching 并在 <Suspense> 内部等待 params。有关详情,请参阅 ISR 与 Cache Components。

不支持 dynamicParams#

启用 Cache Components 时,请移除 dynamicParams 导出。请参阅 dynamicParams 与 Cache Components以了解如何处理缺失的内容。

在 <Suspense> 内部等待 params#

对于不使用 generateStaticParams 的路由,请将 params promise 传入 <Suspense> 边界,而不是在组件顶部等待它。这样 Next.js 可以在参数尚未知时预渲染静态外壳。对于使用 generateStaticParams 的路由,请遵循上文的 ISR 指南。

app/blog/[slug]/page.tsx
// 之前——在顶部等待 params 会阻塞外壳
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  return <Post slug={slug} />
}
app/blog/[slug]/page.js
// 之前——在顶部等待 params 会阻塞外壳
export default async function Page({ params }) {
  const { slug } = await params
  return <Post slug={slug} />
}
app/blog/[slug]/page.tsx
import { Suspense } from 'react'

// 之后——在 Suspense 内部等待,以便外壳可以预渲染
export default function Page({ params }: PageProps<'/blog/[slug]'>) {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Post params={params} />
    </Suspense>
  )
}

async function Post({ params }: Pick<PageProps<'/blog/[slug]'>, 'params'>) {
  const { slug } = await params
  // ...
}
app/blog/[slug]/page.js
import { Suspense } from 'react'

// 之后——在 Suspense 内部等待,以便外壳可以预渲染
export default function Page({ params }) {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Post params={params} />
    </Suspense>
  )
}

async function Post({ params }) {
  const { slug } = await params
  // ...
}

读取路由的 Client 端 hook 遵循相同的 Suspense 模式。当路由的 pathname 完全已知时,它们会在预渲染期间解析,无需边界。当 pathname 依赖于尚未知的动态参数时,hook 会在组件所在的任何位置挂起。例如,共享布局中的导航或面包屑会在 Next.js 为其下方任何具有动态参数的路由生成静态外壳时挂起。请将读取 hook 的组件包裹在 <Suspense> 中(将读取操作下推到最小的叶子节点,以便其余部分保持预渲染),否则构建会失败:

useSearchParams hook 始终需要 <Suspense> 边界,因为 search params 只有在请求时才知道。有关修复方法,请参阅 Next.js 在 Suspense 之外的 Client Component 中遇到 URL 数据。

cookies、headers 与 searchParams#

将运行时数据访问包裹在 <Suspense> 中。 在没有 Cache Components 的情况下,读取 cookies()、headers() 或 searchParams 会使整个路由进入动态渲染。使用 Cache Components 时,在 <Suspense> 边界之外访问它们会呈现 blocking-prerender-runtime 洞察。请将访问操作移入一个包裹在 <Suspense> 中的组件,以便页面的其余部分预渲染为静态外壳,而动态部分在请求时流式传入。

app/page.tsx
import { cookies } from 'next/headers'

// 之前——在顶部读取 cookies 会使整个路由变为动态
export default async function Page() {
  const theme = (await cookies()).get('theme')?.value
  return <Dashboard theme={theme} />
}
app/page.js
import { cookies } from 'next/headers'

// 之前——在顶部读取 cookies 会使整个路由变为动态
export default async function Page() {
  const theme = (await cookies()).get('theme')?.value
  return <Dashboard theme={theme} />
}
app/page.tsx
import { cookies } from 'next/headers'
import { Suspense } from 'react'

// 之后——页面会预渲染;只有 Dashboard 在请求时流式渲染
export default function Page() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Dashboard />
    </Suspense>
  )
}

async function Dashboard() {
  const theme = (await cookies()).get('theme')?.value
  // ...
}
app/page.js
import { cookies } from 'next/headers'
import { Suspense } from 'react'

// 之后——页面会预渲染;只有 Dashboard 在请求时流式渲染
export default function Page() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Dashboard />
    </Suspense>
  )
}

async function Dashboard() {
  const theme = (await cookies()).get('theme')?.value
  // ...
}

你的页面会以 props 的形式接收 params 和 searchParams,两者都是 promise。应用相同的模式:将 promise 直接作为 prop 传递给 <Suspense> 包裹的组件,并在那里 await 它,而不是在页面顶部。你也可以使用 .then() 内联解包 promise 并向下传递普通值;有关类似模式,请参阅 Streaming。

app/page.tsx
import { Suspense } from 'react'

export default function Page({ searchParams }: PageProps<'/'>) {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Results searchParams={searchParams} />
    </Suspense>
  )
}

async function Results({ searchParams }: Pick<PageProps<'/'>, 'searchParams'>) {
  const { query } = await searchParams
  // ...
}
app/page.js
import { Suspense } from 'react'

export default function Page({ searchParams }) {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Results searchParams={searchParams} />
    </Suspense>
  )
}

async function Results({ searchParams }) {
  const { query } = await searchParams
  // ...
}

小知识:当 cookie 或 header 值驱动根布局中 <html> 元素的某个属性(lang、dir、data-theme 等)时,在服务端读取它会使整个子树与请求绑定,因此没有可包裹在 <Suspense> 中的子组件。在 <head> 中使用内联 <script> 在绘制前设置该属性,可以保持外壳为静态;有关此模式,请参阅防止 hydration 前的闪烁。

Route Handlers(GET)#

用 use cache 和 cacheLife 替换 dynamic = 'force-static' 和 revalidate。

使用 Cache Components 时,GET Route Handlers遵循与页面相同的模型:当它们不访问未缓存或运行时数据时,会进行预渲染。移除 dynamic 和 revalidate 配置,并将应被缓存的数据访问移入一个标记了 use cache 的单独函数中。使用 cacheLife 设置其重新验证时间。该指令无法直接应用于 GET 导出本身,因此处理程序会调用一个已缓存的辅助函数。

app/api/products/route.ts
// 之前
export const dynamic = 'force-static'

export async function GET() {
  const products = await db.query('SELECT * FROM products')
  return Response.json(products)
}
app/api/products/route.js
// 之前
export const dynamic = 'force-static'

export async function GET() {
  const products = await db.query('SELECT * FROM products')
  return Response.json(products)
}
app/api/products/route.ts
// 之后
import { cacheLife } from 'next/cache'

export async function GET() {
  const products = await getProducts()
  return Response.json(products)
}

async function getProducts() {
  'use cache'
  cacheLife('hours')
  return db.query('SELECT * FROM products')
}
app/api/products/route.js
// 之后
import { cacheLife } from 'next/cache'

export async function GET() {
  const products = await getProducts()
  return Response.json(products)
}

async function getProducts() {
  'use cache'
  cacheLife('hours')
  return db.query('SELECT * FROM products')
}

小知识: 在 GET 处理程序中读取未缓存或运行时数据会通过抛出异常来退出预渲染。你原本围绕其他操作添加的 try/catch 会捕获该退出。如果 catch 块记录了该错误,会给构建输出增加噪音。设置 experimental.hideLogsAfterAbort: true 可隐藏退出后发出的日志。

generateMetadata 与 generateViewport#

使用 use cache 缓存外部数据,或将页面显式标记为动态。 在 Cache Components 下,generateMetadata 和 generateViewport 遵循与组件相同的规则。如果它们读取运行时数据(cookies()、headers()、params、searchParams)或在页面其余部分可预渲染的情况下获取未缓存的数据,Next.js 会抛出错误,以便你做出明确选择。如果元数据依赖于外部数据但不是运行时数据,请添加 use cache。

app/page.tsx
// 之前
export async function generateMetadata() {
  const { title, description } = await db.query('site-metadata')
  return { title, description }
}
app/page.tsx
// 之后——缓存外部数据
export async function generateMetadata() {
  'use cache'
  const { title, description } = await db.query('site-metadata')
  return { title, description }
}

如果元数据确实需要运行时数据,你不能将 generateMetadata 包裹在 <Suspense> 中。相反,请向页面添加一个动态标记组件,以便静态内容仍能预渲染,而元数据流式传入。

app/page.tsx
import { Suspense } from 'react'
import { connection } from 'next/server'

export async function generateMetadata() {
  // 读取运行时数据
  return { title: 'Personalized Title' }
}

async function DynamicMarker() {
  return (
    <Suspense>
      <Connection />
    </Suspense>
  )
}

async function Connection() {
  await connection()
  return null
}

export default function Page() {
  return (
    <>
      <article>Static content</article>
      <DynamicMarker />
    </>
  )
}

请参阅 generateMetadata 与 Cache Components 和 generateViewport 与 Cache Components,了解完整的修复选项和权衡取舍。

runtime = 'edge'#

移除 runtime 导出。 Cache Components 需要 Node.js 运行时(这是默认设置),且不支持 runtime 路由段配置。即使设置为 runtime = 'nodejs',也要移除该导出。如果某个路由使用了已弃用的runtime = 'edge' 导出,请移除它,并在需要边缘行为时使用 Proxy。

experimental_ppr#

已移除。请改用 cacheComponents。 Next.js 16 移除了实验性的 Partial Prerendering 标志(experimental.ppr)和 experimental_ppr 路由段配置。Partial Prerendering 现在是 Cache Components 的一部分,因此请从 next.config 中移除 experimental.ppr,并从你的路由段中移除 experimental_ppr。可以使用 codemod 为你移除该路由段配置。

app/page.tsx
// 之前——不再需要
export const experimental_ppr = true

export default function Page() {
  return <div>...</div>
}
app/page.js
// 之前——不再需要
export const experimental_ppr = true

export default function Page() {
  return <div>...</div>
}
app/page.tsx
// 之后——移除它;cacheComponents 会启用 Partial Prerendering
export default function Page() {
  return <div>...</div>
}
app/page.js
// 之后——移除它;cacheComponents 会启用 Partial Prerendering
export default function Page() {
  return <div>...</div>
}

UI 状态保留#

组件状态现在会跨导航保留。 使用 Cache Components 时,Next.js 会使用 React 的 <Activity> 组件以 "hidden" 模式保留路由,而不是卸载它们。Effect 会正常清理并重新运行,但当导航离开再返回时,useState 值、表单输入和滚动位置不会再被重置。

如果你的代码依赖卸载来清除状态,你可能需要添加显式的重置逻辑:

  • 下拉菜单和弹出框:导航返回时会保持打开。请在 useLayoutEffect 的清理函数中关闭它们。
  • 带有初始化逻辑的对话框:如果状态被保留,依赖于对话框状态的 Effect(例如聚焦输入框)不会重新触发。请改为从 URL 派生对话框状态。
  • 提交后的表单:返回时,输入值和 useActionState 结果(成功/错误消息)会保留。请尽可能在提交处理程序或用户操作中重置,否则使用清理 Effect。

请参阅跨导航保留 UI 状态,了解每种模式的详细示例。

Next.js 中文网