nextjs-caching

Next.js 缓存

关于 Next.js 缓存机制、ISR 模式和常见陷阱的专家指南。

核心概念

"use cache" 指令

将组件或函数标记为可缓存。该指令不会立即缓存，而是将输出标记为在构建时缓存。

"use cache"
export default function MyComponent() {
  // Output cached at build time
}

应用于页面的主组件时，会创建类似 ISR 的行为，缓存整个输出（不进行部分缓存）。

自动静态渲染

Next.js 从上到下进行渲染，直到遇到动态 API，然后创建一个“动态空洞”。除非要强制整个页面采用 ISR 行为，否则无需显式使用 "use cache"。

缓存函数不被视为动态内容，也不会创建空洞。

两阶段渲染

1. 预热渲染（预测性）：检测动态 API 的使用情况。任何未在微任务中解析的内容都会被视为动态内容。
2. 最终渲染：捕获实际输出，以便进行预渲染。

重新验证 API

revalidateTag 与 updateTag

• revalidateTag：在服务器操作中使用时，以 stale-while-revalidate 方式重新验证。获取新数据时仍提供过期内容。
• updateTag：采用读取自己的写入（read-your-own-writes）模式，立即清除之前的缓存。不能在路由处理程序中使用。

注意：尽管名称如此，revalidatePath 实际上在底层是 revalidateTag——其参数（某种程度上）是一个路径。

connection() 替代方案

使用 connection() 替代 unstable_noStore()，将函数标记为动态。

ISR 模式

使用 "use cache" 的 Suspense 边界

带有 "use cache" 和 Suspense 边界的组件，其工作方式类似 ISR：

1. 首次请求触发 Suspense 边界
2. 显示内容并缓存结果
3. 后续请求提供缓存的内容

要让 Suspense 保持动态，请将静态内容移至单独的缓存组件中。

跨边界访问缓存值

缓存函数的输出（而不只是组件），以便在布局和页面之间重复使用值。再次调用缓存函数即可获取该值。

部分页面缓存

对于混合静态/动态页面：

• 页面不使用 "use cache"
• 缓存各个组件
• 将动态组件封装在 Suspense 中
• 替代方案：使用并行路由

动态路由与 generateStaticParams

关键要求

在 generateStaticParams 中至少导出一个参数，以生成静态外壳并启用 ISR 行为。

export function generateStaticParams() {
  return [{ id: 'placeholder' }] // Handle this case in render
}

如果没有 generateStaticParams，动态页面会因读取参数的上方缺少 Suspense 而失败。

解决方法：添加 loading.tsx，或在主体周围添加空的 Suspense，以阻塞服务器。

缓存持久性

unstable_cache 与 "use cache: remote"

• unstable_cache：在多次部署之间持久保留
• "use cache: remote"：不会在多次部署之间持久保留

构建时的缓存快照

可缓存函数在构建时被调用时会生成快照。在动态组件中使用 "use cache" 函数，只有在构建时捕获了快照，才能保证缓存命中。否则会从内存缓存中提供内容。

性能与基础设施

短缓存行为

stale 小于 30 秒的缓存属于“短缓存”，不会纳入运行时预取。

边缘代理弹性

返回静态外壳的代理运行在边缘。它会立即返回外壳，并继续请求动态内容。如果某个区域发生故障，代理仍会继续工作。

unstable_cache 性能

就渲染而言，unstable_cache 函数会被视为即时完成。

调试

验证静态页面

构建日志有时会为静态页面显示 ppr。最可靠的验证方法：检查文档请求中的 x-nextjs-cache: HIT 标头。

布局中的 "use cache" 注意事项

在布局中设置 "use cache"，但不在页面中设置，并不会使页面变为静态。

参考资料

• references/detailed-guide.md：提供所有缓存模式的全面示例和详细说明。在实现特定缓存策略或调试缓存行为时阅读。