用途:为 Next.js 项目提供 Cache Components 与部分预渲染(PPR)的实现指导,目标是构建可用的预渲染外壳,并让新鲜度与授权规则在变更、部署和客户端导航后仍然正确。
主要能力:指导 use cache 指令、cacheLife/cacheTag 缓存生命周期与标签失效、Suspense 边界划分、instant-navigation 校验,以及从旧缓存模式迁移。
必要用法:应用前先确认已安装的 Next.js 版本与 cacheComponents/partialPrefetching 配置,并优先阅读 node_modules/next/dist/docs/ 中的相关指南;精确导出与签名见 node_modules/next/cache.d.ts。Next.js 16 通过顶层 cacheComponents: true 启用,替代 experimental.dynamicIO、experimental.useCache 和 experimental.ppr;cacheLife/cacheTag 从 next/cache 导入,不带 unstable_。16.4 需显式设置 partialPrefetching。启用后,段级 dynamic、revalidate、fetchCache、dynamicParams 导出会报错,且不支持 Edge 运行时。
限制:普通 use cache 作用域不能读取 cookies、headers、searchParams 或调用 connection();账户/租户 ID 需参与缓存键。use cache 默认内存缓存,部署 ID 变化后无法复用。generateStaticParams 必须返回至少一个参数。revalidate: 0 或 expire 小于 5 分钟会产生请求时漏洞。预渲染期间同步调用 new Date()、Math.random()、crypto.randomUUID() 会报错。use cache: private 在 16.2 前为实验性。私有缓存不构成合规保证,远程缓存不是一致性协议。具体配置与行为以已安装版本文档为准。