在 Next.js 16+ 中启用 Cache…

当 Next.js 16+ 项目需要部分预渲染、混合静态与动态内容，并用 use cache、cacheLife、cacheTag、updateTag/revalidateTag 管理缓存时使用。

适用场景

解决思路

1. 在 `next.config.ts` 中导入 `NextConfig` 类型，并将 `cacheComponents` 设为 `true`，以启用 Cache Components；它替代旧的 `experimental.ppr` 标志。
2. 将页面内容按三类划分：静态内容用同步代码、导入、纯计算，构建时自动预渲染；缓存内容用 `'use cache'` 处理不需要每次请求都获取的异步数据；动态内容用 `Suspense` 包裹并读取运行时数据。
3. 对静态内容：直接返回同步 JSX，例如页头、导航等，无需额外指令，构建时预渲染并立即返回。
4. 对缓存内容：在异步函数或组件顶部添加 `'use cache'`，调用 `cacheLife(...)` 设置生命周期，然后执行数据库查询或 fetch 并返回 JSX。
5. 对动态内容：用 `<Suspense fallback={...}>` 包裹需要运行时数据的组件，在组件内部调用 `cookies()` 等运行时 API，使其在请求时流式渲染。
6. 在文件级别使用 `'use cache'`：在模块顶部写 `'use cache'`，使整个页面或模块被缓存。
7. 在组件级别使用 `'use cache'`：在异步组件函数体第一行写 `'use cache'`，只缓存该组件。
8. 在函数级别使用 `'use cache'`：在数据函数第一行写 `'use cache'`，缓存该函数的返回结果。
9. 使用默认缓存配置：`'use cache'` 不额外配置时采用默认 5 分钟 stale、15 分钟 revalidate。
10. 使用平台缓存：写 `'use cache: remote'` 使用平台提供的缓存，如 Redis、KV。
11. 使用私有缓存：写 `'use cache: private'` 以满足合规要求，并允许在缓存函数内访问运行时 API。
12. 使用 `cacheLife()`：从 `next/cache` 导入 `cacheLife`，在 `'use cache'` 函数内调用内置 profile：`'default'`、`'minutes'`、`'hours'`、`'days'`、`'weeks'`、`'max'`。
13. 使用内联 `cacheLife` 配置：传入对象 `{ stale: 3600, revalidate: 7200, expire: 86400 }`，分别控制 stale 服务时间、后台 revalidate 间隔、硬过期时间。
14. 使用 `cacheTag()`：从 `next/cache` 导入 `cacheTag`，在 `'use cache'` 函数内给缓存打标签，例如 `cacheTag('products')` 或 `cacheTag('products', `product-${id}`)`。
15. 使用 `updateTag()`：在 `'use server'` 的 server action 中，数据更新后调用 `updateTag(`product-${id}`)`，让同一请求立即看到最新数据并刷新缓存。
16. 使用 `revalidateTag()`：在 `'use server'` 的 server action 中，数据创建或更新后调用 `revalidateTag('posts')`，实现 stale-while-revalidate，让下一个请求看到新数据。
17. 遵守运行时数据限制：不要在 `'use cache'` 内访问 `cookies()`、`headers()` 或 `searchParams`。
18. 处理运行时数据限制：在 `'use cache'` 外部读取 `cookies()`、`headers()` 或 `searchParams`，把值作为参数传给缓存函数；该参数会自动成为缓存键的一部分。
19. 合规例外：当无法重构且必须访问运行时 API 时，使用 `'use cache: private'` 允许在缓存函数内访问 `cookies()` 等。
20. 依赖自动缓存键：缓存键自动包含 Build ID（部署时失效全部缓存）、Function ID（函数位置哈希）、可序列化参数（props 进入键）、闭包变量（外层作用域值进入键）。
21. 设计闭包或参数键：例如组件接收 `userId`，内部缓存函数接收 `filter`，则缓存键由 `userId`（闭包）和 `filter`（参数）共同组成。
22. 组合完整页面：页面中混合静态 shell（header 和 nav 直接从 CDN 瞬间返回）、缓存区块（用 `'use cache'` + `cacheLife('hours')` + `cacheTag('dashboard-stats')`）、动态区块（用 `Suspense` 包裹并在内部读取 `cookies()`）。
23. 从旧配置迁移：将 `experimental.ppr` 替换为 `cacheComponents: true`。
24. 从旧配置迁移：移除 `dynamic = 'force-dynamic'`，因为默认行为已符合。
25. 从旧配置迁移：将 `dynamic = 'force-static'` 替换为 `'use cache'` + `cacheLife('max')`。
26. 从旧配置迁移：将 `revalidate = N` 替换为 `cacheLife({ revalidate: N })`。
27. 从旧配置迁移：将 `unstable_cache()` 替换为 `'use cache'` 指令。
28. 迁移 `unstable_cache`：不再传手动 cache key 数组；`use cache` 会根据函数参数和闭包自动生成键，原有 `keyParts` 不再需要。
29. 迁移 `unstable_cache`：将 `options.tags` 替换为函数内调用 `cacheTag()`。
30. 迁移 `unstable_cache`：将 `options.revalidate` 替换为 `cacheLife({ revalidate: N })` 或内置 profile，如 `cacheLife('minutes')`。
31. 迁移 `unstable_cache` 的动态数据限制：`unstable_cache` 不支持在回调内使用 `cookies()` 或 `headers()`，`use cache` 同样限制；如有需要改用 `'use cache: private'`。
32. 注意运行环境限制：Cache Components 不支持 Edge runtime，需要 Node.js。
33. 注意部署限制：Cache Components 不支持 static export，需要服务器。
34. 处理非确定性值：`Math.random()`、`Date.now()` 等非确定性值在 `'use cache'` 内只会在构建时执行一次，不会每次请求变化。
35. 需要请求时随机性时：从 `next/server` 导入 `connection`，在动态组件中先 `await connection()` 推迟到请求时，再调用 `crypto.randomUUID()` 等生成每次请求不同的值。

适用边界 · 注意事项

• 不适用于 Next.js 16 以下或未启用 `cacheComponents` 的项目，需要先升级并启用该配置。
• 不适用于 Edge runtime 或 static export 部署，因为 Cache Components 需要 Node.js 服务器。
• 不适用于无法接受缓存陈旧且不能使用 `updateTag`、`revalidateTag` 或动态 Suspense 的场景；需要请求时非确定性值时必须用 `connection()` 放到缓存外。