cacheComponents
了解如何在 Next.js 中启用 cacheComponents 标志。
Cache Components 使用 use cache 指令支持组件级和函数级缓存。数据获取默认是动态的,你可以选择在页面、组件或函数级别缓存哪些内容。Next.js 会预渲染一个静态 HTML 外壳并立即提供,而动态内容在就绪时流式传输,使你能够在单个路由中混合静态和动态内容。
用法#
要启用 cacheComponents 标志,请在 next.config.ts 文件中将其设置为 true,并同时设置 partialPrefetching:
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 后,你可以使用以下缓存函数和配置:
use cache指令- 与
use cache配合使用的cacheLife函数 cacheTag函数
小知识:如果你使用了
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.0 | cacheComponents 已稳定,并从 experimental.cacheComponents 移至顶层的 cacheComponents 选项。该标志将 ppr、useCache 和 dynamicIO 标志统一为单一配置进行控制。 |