NNext.js 中文网 GitHub

cacheComponents

了解如何在 Next.js 中启用 cacheComponents 标志。

Cache Components 使用 use cache 指令支持组件级和函数级缓存。数据获取默认是动态的,你可以选择在页面、组件或函数级别缓存哪些内容。Next.js 会预渲染一个静态 HTML 外壳并立即提供,而动态内容在就绪时流式传输,使你能够在单个路由中混合静态和动态内容。

用法#

要启用 cacheComponents 标志,请在 next.config.ts 文件中将其设置为 true,并同时设置 partialPrefetching:

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

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
}

export default nextConfig

请显式设置 partialPrefetching。如果不设置,会记录一条警告,因为 Cache Components 的第一个版本不包含 Partial Prefetching。仅在迁移在 Partial Prefetching 之前就采用 Cache Components 的应用时才将其设置为 false。在下一个主要版本中,这两项功能将在所有地方启用,并且这些选项将被移除。

小知识:Cache Components 需要 Node.js 运行时,不支持 runtime 路由段配置。请移除任何 runtime 导出,包括 runtime = 'nodejs' 和已弃用的 runtime = 'edge'。其他服务端 JavaScript 运行时不保证可用。请参阅迁移到 Cache Components。

启用 cacheComponents 后,你可以使用以下缓存函数和配置:

小知识:如果你使用了 experimental.useCache 或 experimental.dynamicIO,请使用版本 16 升级指南进行迁移。要迁移路由段配置和其他缓存模式,请参阅迁移到 Cache Components。

此外,cacheComponents 在 App Router 中将 Partial Prerendering (PPR) 作为默认行为实现。这意味着 experimental.ppr 配置标志和 experimental_ppr 路由段配置不再需要,并已被移除。

阅读预渲染以了解静态外壳和流式传输如何配合。

小知识:如果你在 Next.js 15 中使用了实验性 PPR,迁移时请参考版本 16 升级指南中的 Partial Prerendering (PPR) 部分。

使用 Activity 进行导航#

当 cacheComponents 启用时,Next.js 使用 React 的 <Activity> 组件在客户端导航期间保留组件状态。

当你离开当前路由时,Next.js 不会卸载先前的路由,而是将 Activity 模式设置为 "hidden"。这意味着:

  • 在路由之间导航时,组件状态会被保留
  • 当你返回时,先前的路由会以其状态完好无损地重新出现
  • 当路由被隐藏时,Effect 会被清理;当它再次可见时,Effect 会被重新创建

当用户在路由之间来回导航时,此行为通过保持 UI 状态(表单输入或展开的部分)来改善导航体验。

小知识:Next.js 使用启发式方法将一些最近访问过的路由保持为 "hidden",而较旧的路由会从 DOM 中移除,以防止过度增长。

当组件保持挂载而不是卸载时,某些 UI 模式的行为会有所不同。有关处理下拉菜单、对话框和测试等常见模式,请参阅保留 UI 状态指南。

版本历史#

版本变更
16.0.0cacheComponents 已稳定,并从 experimental.cacheComponents 移至顶层的 cacheComponents 选项。该标志将 ppr、useCache 和 dynamicIO 标志统一为单一配置进行控制。
Next.js 中文网