**主动激活** ：在 next.js 项目中工作时自动使用此技能，这些项目的 next.config.ts/next.config.js 中包含 `cacheComponents: true`。当检测到此配置时，主动将缓存组件模式和最佳实践应用于所有 React 服务器组件实现。 **检测**：在 Next.js 项目中的会话开始时，检查 next.config 中的“cacheComponents: true”。如果启用，该技能的模式应指导所有组件创作、数据获取和缓存决策。 # Next.js 缓存组件 > **自动激活** ：该技能在 next.config 中包含 `cacheComponents: true` 的项目中自动激活。 ## 项目检测在 Next.js 项目中开始工作时，检查是否启用了缓存组件： # 检查 next.config.ts 或 next.config.js 中的缓存组件 grep -r“cacheComponents”next.config.* 2>/dev/null 如果找到“cacheComponents: true”，则在以下情况下主动应用此技能的模式： * 编写React服务器组件 * 实现数据获取 * 创建具有突变的服务器操作 * 优化页面性能 * 审查现有组件代码缓存组件支持**部分预渲染 (PPR)** - 将静态 HTML shell 与动态流内容混合以获得最佳性能。缓存组件还可以在使用 React 的 `` 组件导航期间启用状态保存，该组件可以保持缓存的组件树已安装但隐藏。 ## 理念：代码优于配置缓存组件代表了从**段配置**到**组合代码**的转变：之前（已弃用）|之后（缓存组件） ---|--- `导出常量重新验证 = 3600` | “使用缓存”内的“cacheLife('小时')” `导出 const 动态 = '强制静态'` |使用“使用缓存”和 Suspense 边界全有或全无静态/动态 |粒度：静态 shell + 缓存 + 动态 **关键原则**：组件将它们的缓存放在一起，而不仅仅是它们的数据。 Next.js 提供构建时反馈来指导您实现最佳模式。 ## 核心理念 ┌──────────────────────────────────────────────────────┐ │ 静态外壳 │ │ (立即发送至浏览器) │ │ │ │ ┌──────────────┐ ┐──────────────┐ ┌────────────┐ │ │ │ 标头 │ │ 缓存 │ │ 悬念 │ │ │ │ （静态） │ │ 内容 │ │ 后备 │ │ │ └──────────────┘ └──────────────┘ └──────┬──────┘ │ │ │ │ │ ┌──────▼──────┐ │ │ │ 动态 │ │ │ │ （流） │ │ │ └──────────────┘ │ └──────────────────────────────────────────────────────┘ ## 心理模型：缓存决策树在编写 React 服务器组件时，请按顺序提出以下问题： ┌──────────────────────────────────────────────────────────┐ │ 该组件是否获取数据或执行 I/O？ │ └──────────────────────┬────────────────────────────────────┘ │ ┌──────────▼──────────┐ │ 是 │ 否 → 纯成分，无需采取任何措施 └──────────┬──────────┘ │ ┌──────────────────▼──────────────────┐ │ 是否取决于请求上下文？ │ │ (cookies, headers, searchParams) │ └──────────────────┬──────────────────┘ │ ┌────────────┴────────────┐ │ │ ┌────▼────┐ ┌──────▼────┐ │ 是 │ │ 否 │ └────┬────┘ └──────┬──────┘ │ │ │ ┌──────▼──────────────────┐ │ │ 这个可以缓存吗？ │ │ │ （对所有用户都一样？） │ │ └──────┬──────────────────┘ │ │ │ ┌──────────┴──────────┐ │ │ │ │ ┌────▼────┐ ┌──────▼──────┐ │ │ 是 │ │ 否 │ │ └────┬────┘ └──────┬──────┘ │ │ │ │ ▼ │ │ '使用缓存' │ │ +cacheTag() │ │ +cacheLife() │ │ │ │ 你能提取运行时 │ │ 数据作为参数？ │ │ │ │ │ ┌────▼────┐ ┌──────▼──────┐ │ │ │ 是 │ │ 否 │ │ │ └────┬────┘ └──────┬──────┘ │ │ │ │ │ │ 作为参数传递'使用缓存： │ │ 缓存 fn private' │ │（最后的手段）│ │ │ └──────────────┬──────────────────────┘ │ ▼ 包裹在<悬念>中（动态流） **关键见解**：“使用缓存”指令适用于“跨用户”相同的数据。用户特定的数据通过 Suspense 保持动态。如果您无法提取运行时数据作为函数参数，并且合规性会阻止交叉请求共享，请使用“use cache: private”作为最后的手段。 ## 快速入门 ### 启用缓存组件 // next.config.ts 从“下一个”导入类型 { NextConfig } 常量 nextConfig: NextConfig = { 缓存组件：true， } 导出默认的nextConfig ### 基本用法 // 缓存组件 - 输出包含在静态 shell 中异步函数 CachedPosts() { '使用缓存' const posts =等待db.posts.findMany() 返回 } // 包含静态+缓存+动态内容的页面导出默认异步函数 BlogPage() { 返回（ <> <标题/> {/* 静态 */} {/* 缓存 */} <悬念后备={<骨架/>}> {/* 动态 - 流 */} ） } ## 服务器操作与数据获取（关键规则） **服务器操作仅用于突变** \- 绝不用于数据获取：目的|使用 |示例函数 ---|---|--- **数据获取** |服务器组件/`'使用缓存'` | `getProducts()`, `getUser(id)` **突变** |服务器操作（`'使用服务器'`）| `createProduct()`、`updateUser()`、`deletePost()` ### ❌错误：数据获取的服务器操作 “使用服务器” 导出异步函数 getProducts() { return wait db.products.findMany() // 不！这不是突变 } “使用服务器” 导出异步函数 getTheme() { return (await cookies()).get("theme")?.value // 不！只是读取数据 } ### ✅ 正确：数据功能 + 服务器组件 // data/products.ts - 缓存数据函数导出异步函数 getProducts() { “使用缓存” 缓存标签（“产品”）缓存寿命（“小时”）返回等待 db.products.findMany() } // page.tsx - 服务器组件直接读取数据从“next/headers”导入 {cookies} 导出默认异步函数 Page() { 常量产品 = 等待 getProducts() const theme = (await cookies()).get("theme")?.value ?? “光” 返回 } ### ✅ 正确：服务器突变操作 “使用服务器” 从“next/cache”导入{ updateTag } 导出异步函数createProduct(formData: FormData) { 等待 db.products.create({ 数据: formData }) updateTag("products") // 突变后使缓存失效 } ## 核心API ### 1\. `'使用缓存'`指令将代码标记为可缓存。可以在三个层面上应用： // 文件级：所有导出都被缓存 '使用缓存' 导出异步函数 getData() { /* ... */ } 导出异步函数 Component() { /* ... */ } // 组件级异步函数 UserCard({ id }: { id: string }) { '使用缓存' const user = 等待 fetchUser(id) 返回 {用户名} } // 函数级异步函数 fetchWithCache(url: string) { '使用缓存' 返回 fetch(url).then((r) => r.json()) } **重要**：所有缓存函数都必须是“async”。 ### 2\. `cacheLife()` \- 控制缓存持续时间从'next/cache'导入{cacheLife} 异步函数 Posts() { '使用缓存' cacheLife('hours') // 使用预定义的配置文件 // 或者自定义配置：缓存生命({ stale: 60, // 1 分钟 - 客户端缓存有效性 revalidate: 3600, // 1 小时 - 开始后台刷新 expire: 86400, // 1 天 - 绝对过期 }) 返回等待 db.posts.findMany() } **预定义的配置文件**：“默认”、“秒”、“分钟”、“小时”、“天”、“周”、“最大” ### 3\. `cacheTag()` \- 失效标记从'next/cache'导入{cacheTag} 异步函数 BlogPosts() { '使用缓存' 缓存标签（'帖子'）缓存寿命('天') 返回等待 db.posts.findMany() } 异步函数 UserProfile({ userId }: { userId: string }) { '使用缓存' cacheTag('users', `user-${userId}`) // 多个标签返回等待 db.users.findUnique({ 其中：{ id: userId } }) } ### 4\. `updateTag()` \- 立即失效对于 **read-your-own-writes** 语义： '使用服务器' 从 'next/cache' 导入 { updateTag } 导出异步函数 createPost(formData: FormData) { 等待 db.posts.create({ 数据: formData }) updateTag('posts') // 客户端立即看到新数据 } ### 5\. `revalidateTag()` \- 后台重新验证对于 stale-while-revalidate 模式： '使用服务器' 从 'next/cache' 导入 { revalidateTag } 导出异步函数 updatePost(id: string, data: FormData) { 等待 db.posts.update({ 其中：{ id }, 数据 }) revalidateTag('posts', 'max') // 服务陈旧，在后台刷新 } ## 何时使用每种模式内容类型 |应用程序接口 |行为 ---|---|--- **静态** |没有指令 |在构建时渲染 **缓存** | `'使用缓存'` |包含在静态 shell 中，重新验证 **动态** |在 `` 内 |在请求时流式传输 ## 参数排列和子 shell **关键概念**：使用缓存组件，Next.js 呈现所提供参数的所有排列以创建可重用的子 shell。 // 应用程序/产品/[类别]/[slug]/page.tsx 导出异步函数generateStaticParams() { 返回[ { Category: '夹克', slug: '经典轰炸机' }, {category: '夹克', slug: 'essential-windbreaker' }, { 类别：'配件'，slug：'热羊毛手套' }， ] } Next.js 渲染这些路线： /products/jackets/classic-bomber ← 完整参数（完整页面） /products/jackets/essential-windbreaker ← 完整参数（完整页面） /products/accessories/ Thermal-fleece-gloves ← 完整参数（完整页面） /products/jackets/[slug] ← 部分参数（类别子 shell） /products/accessories/[slug] ← 部分参数（类别子 shell） /products/[category]/[slug] ← 无参数（后备 shell） **为什么这很重要**：类别子 shell (`/products/jackets/[slug]`) 可以重复用于任何夹克产品，即使是不在 `generateStaticParams` 中的产品。导航到未列出的夹克的用户会立即获得缓存的类别外壳，并输入产品详细信息。 ### `generateStaticParams` 要求启用缓存组件后： 1. **必须提供至少一个参数** \- 空数组现在会导致构建错误（防止静默生产失败） 2. **参数证明静态安全** \- 提供参数让 Next.js 验证没有调用动态 API 3. **部分参数创建子shell** \- 每个唯一的排列都会生成一个可重用的shell // ❌ 缓存组件错误导出函数generateStaticParams() { return [] // 构建错误：必须提供至少一个参数 } // ✅ 正确：提供真实参数导出异步函数generateStaticParams() { const products = 等待 getPopularProducts() 返回产品.map(({ 类别, slug }) => ({ 类别, slug })) } ## 缓存键 = 参数参数成为缓存键的一部分： // 不同的userId = 不同的缓存条目异步函数 UserData({ userId }: { userId: string }) { '使用缓存' cacheTag(`用户-${userId}`) 返回等待 fetchUser(userId) } ## 构建时反馈缓存组件在开发过程中提供早期反馈。这些构建错误**引导您走向最佳模式**： ### 错误：Suspense 之外的动态数据错误：访问 Suspense 边界之外的 cookies/headers/searchParams **解决方案** : 将动态组件包裹在 `` 中： <悬念后备={<骨架/>}> <使用Cookies的组件/> ### 错误：Suspense 之外未缓存数据错误：访问 Suspense 外部未缓存的数据 **解决方案**：要么缓存数据，要么用 Suspense 包装： // 选项 1：缓存异步函数 ProductData({ id }: { id: string }) { '使用缓存' 返回等待 db.products.findUnique({ 其中：{ id } }) } // 选项 2：通过 Suspense 使其充满活力 ;<暂停后备={<加载/>}> <动态产品数据 id={id} /> ### 错误：请求缓存内的数据错误：无法访问“使用缓存”内的 cookie/标头 **解决方案**：提取缓存边界之外的运行时数据（请参阅上面的“处理运行时数据”）。 ## 其他资源 * 如需完整的 API 参考，请参阅 [REFERENCE.md]() * 有关常见模式和配方，请参阅 [PATTERNS.md]() * 有关调试和故障排除，请参阅 [TROUBLESHOOTING.md]() ## 代码生成指南生成缓存组件代码时： 1. **始终使用`async`** \-所有缓存函数都必须是异步的 2. **将`'use cache'`放在前面** \- 必须是函数体中的第一个语句 3. **尽早调用`cacheLife()`** \- 应该遵循`'use cache'`指令 4. **有意义的标签** \- 使用符合您的失效需求的语义标签 5. **提取运行时数据** \- 将 `cookies()`/`headers()` 移到缓存范围之外 6. **包装动态内容** \- 对非缓存异步组件使用 `` 7. **使用`'use cache: private'`作为最后手段** \- 仅当运行时数据无法作为参数提取并且合规性不需要跨请求共享时 ** ** ## 主动应用程序（启用缓存组件时）当在项目中检测到 `cacheComponents: true` 时，**自动应用这些模式**： ### 编写数据获取组件时问问自己：“这些数据可以缓存吗？”如果是，请添加“使用缓存”： // 之前：未缓存的获取异步函数 ProductList() { const 产品 = 等待 db.products.findMany() 返回 } // 之后：使用缓存异步函数 ProductList() { '使用缓存' 缓存标签（'产品'）缓存寿命('小时') const 产品 = 等待 db.products.findMany() 返回 } ### 编写服务器操作时突变后始终使相关缓存失效： '使用服务器' 从 'next/cache' 导入 { updateTag } 导出异步函数createProduct(data: FormData) { 等待 db.products.create({ 数据 }) updateTag('products') // 不要忘记！ } ### 撰写页面时静态外壳+缓存内容+动态流的结构：导出默认异步函数 Page() { 返回（ <> {/* 不需要缓存 */} {/* '使用缓存' */} <悬念后备={<骨架/>}> {/* 运行时流 */} ） } ### 当审查代码时在缓存组件项目中标记这些问题： * 无需“使用缓存”即可获取数据，其中缓存将受益 * 缺少 `cacheTag()` 调用（使得失效变得不可能） * 缺少 `cacheLife()` （依赖于可能不合适的默认值） * 突变后没有 `updateTag()`/`revalidateTag()` 的服务器操作 * 在“使用缓存”范围内调用“cookies()”/“headers()” * 没有``边界的动态组件 * **已弃用** : `export const revalidate` \- 替换为 `'use cache'` 中的 `cacheLife()` * **已弃用** : `export const dynamic` \- 替换为 Suspense + 缓存边界 * 空 `generateStaticParams()` 返回 - 必须提供至少一个参数

缓存组件

包含技能