# Next.js PPR 和缓存代码审查技巧 ## 目的查看 Next.js App Router 代码以获得最佳的部分预渲染 (PPR)、缓存策略、Suspense 边界和 React 查询集成。确保遵守 Next.js 16+ 缓存组件最佳实践。 > **文档版本**：基于 Next.js 16.0.4 官方文档 **最后更新**：2025-11-25 **来源**： ## 何时使用 * 在使用 Next.js 组件创建拉取请求之前 * 实现新的数据获取功能时 * 在性能优化审核期间 * 添加或修改 Suspense 边界时 * 实施缓存策略后 ## 先决条件 * Next.js 16+ 在 next.config 中包含 `cacheComponents: true` * 应用程序路由器（不是页面路由器） * 了解服务器组件与客户端组件 ** ** ## 了解两种缓存系统 > **📖 参考** : [缓存组件 - 带运行时数据]() 在查看代码之前，请了解这两种**完全不同的**缓存机制：概念 |反应 `cache()` | “使用缓存”指令 ---|---|--- **导入** | `从'react'导入{缓存}` |指令：`'使用缓存'` **范围** | **相同请求**重复数据删除 | **交叉请求**缓存 **持续时间** |仅单个渲染通道 |分钟/小时/天 **用例** | `getCurrentUser()` 调用 5x = 1 次实际调用 |为所有用户缓存数据 **与 cookies() 一起使用** | ✅ 是（包装函数）| ❌ 否（使用“使用缓存：私有”） ### 架构层 ┌────────────────────────────────────────────────────────────────────────┐ │ 第 1 层：布局/页面（静态外壳） │ │ ────────────────────────────────────────────────────────────────────── │ │ • 没有 cookies()、没有 headers()、没有运行时数据 │ │ • 在构建时预渲染 → 即时交付 │ │ • 包含尽可能深的边界 │ └──────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ 第 2 层：授权边界（动态 - 悬念内） │ │ ────────────────────────────────────────────────────────────────────── │ │ • 调用 cookies() 来获取会话令牌 │ │ • 使用 getCurrentUser() 封装 React cache() 进行重复数据删除 │ │ • 如果未通过身份验证，则处理重定向（'/login'） │ │ • 将 accessToken DOWN 作为 prop 传递给缓存组件 │ └──────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ 第 3 层：缓存数据（CACHED - “使用缓存”，以令牌为键）│ │ ────────────────────────────────────────────────────────────────────── │ │ • 接收 accessToken 作为 PROP（自动成为缓存密钥） │ │ • 使用“使用缓存”+cacheLife() + cacheTag() │ │ • 使用令牌获取用户特定数据 │ │ • 跨多个请求缓存每个用户 │ └──────────────────────────────────────────────────────────────────────────┘ ### 完整的身份验证+缓存实现 **步骤 1：身份验证实用程序 (`auth/server.ts`)** 从“反应”导入{缓存}；从'next/headers'导入{cookies}；从“下一步/导航”导入{重定向}； // 内部：从 cookie 读取会话（无法缓存 - 运行时数据）异步函数 getSessionFromCookie() { const cookieStore = 等待 cookies(); const session = cookieStore.get('github_session')?.value; 返回会话？解密（会话）：空； } // ✅ 用 React cache() 包装以实现 SAME-REQUEST 重复数据删除 // 如果布局 + 页面 + 10 个组件调用 this = 1 实际读取的 cookie 导出 const getCurrentUser = 缓存(async () => { const session = 等待 getSessionFromCookie(); if (!session) 返回 null；返回{ accessToken：session.githubToken，用户Id：session.githubId，用户名：会话.用户名， }; }); // ✅ Auth Guard - 如果未登录则重定向导出异步函数 requireAuth() { const user = 等待 getCurrentUser(); 如果（！用户）{ 重定向（'/登录'）； } 返回用户； } **步骤 2：布局（静态外壳 - 无运行时数据）** // 应用程序/layout.tsx 导出默认函数 RootLayout({ Children }: { Children: React.ReactNode }) { // ⚠️ 这里没有 cookies()！布局保留在静态外壳中。返回（ <正文> {/* ✅ 静态 shell 的一部分 */} {/* ✅ 静态 shell 的一部分 */} {孩子} {/* ✅ 静态 shell 的一部分 */} ）； } **步骤 3：带有悬念边界的页面（尽可能深）** // 应用程序/pulls/page.tsx 从'react'导入{Suspense}；导出默认函数 PullsPage() { // ✅ 页面本身是静态的 - 这里没有运行时数据访问返回（

拉取请求

{/* ✅ 静态 shell */} {/* ✅ 悬念边界尽可能深 */} }>

）； } **步骤 4：身份验证边界组件（动态）** // 组件/authenticated-pulls-list.tsx 从'@/auth/server'导入{requireAuth}； // ⚠️ 该组件是动态的 - 通过 requireAuth 访问 cookie // ⚠️ 必须在使用站点包裹在中导出异步函数 AuthenticatedPullsList() { // 第 1 步：身份验证检查（读取 cookie，可能会重定向） const user = 等待 requireAuth(); // 步骤 2：将令牌传递给 CACHED 组件（令牌 = 缓存密钥）返回 ; } **步骤 5：缓存数据组件** // 组件/pulls-list-cached.tsx 从'next/cache'导入{cacheLife，cacheTag}； // ✅ 该组件跨请求进行缓存 // ✅ accessToken 是缓存键的一部分 - 每个用户都有自己的缓存异步函数 PullsListCached({ accessToken }: { accessToken: string }) { '使用缓存'； cacheLife('分钟'); // 5 分钟过时，1 分钟重新验证 cacheTag('用户拉取'); // 用于按需失效 // 此获取按用户缓存（由 accessToken prop 指定） const 客户端 = createGitHubClient(accessToken); const pulls =等待client.pulls.list(); 返回（

)}

）； } ### 为什么这种模式是最佳的效益 |它是如何实现的 ---|--- **最大静态外壳** |布局、标题、标题立即预渲染 **悬念尽可能深** |仅数据部分流；其他一切都是即时的 **没有重复的 cookie 读取** | `getCurrentUser()` 与 React `cache()` = 每个请求 1 次读取 **跨请求缓存** |带有令牌键的“使用缓存”=每用户缓存重用 **缓存隔离** |令牌作为 prop = 自动每用户缓存密钥 ### 批判性见解：身份验证发生的地方 // ❌ 错误 - 布局中的身份验证会阻止整个布局进行预渲染导出默认异步函数Layout({children}){ const user = 等待 getCurrentUser(); // cookies() 阻止预渲染！返回

{children}

; } // ✅ 正确 - 布局是静态的，身份验证位于页面的 Suspense 内部导出默认函数Layout({children}){ 返回（

<静态导航/> {children} {/* 页面将身份验证放在自己的 Suspense 中 */}

）； } ### 决策矩阵：使用哪个缓存你在做什么|哪个缓存 |为什么 ---|---|--- `getCurrentUser()` \- 读取 cookies |反应 `cache()` |相同请求重复数据删除；无法缓存交叉请求的cookie `getGitHubClient(token)` \- 创建客户端 |反应 `cache()` |相同请求重复数据删除；重用客户端实例 `fetchUserRepos(token)` \- 使用令牌进行 API 调用 | `'使用缓存'` |跨请求缓存；令牌是缓存键 `fetchPublicRepo(owner, repo)` \- 公共数据 | `'使用缓存'` |跨请求缓存；无需授权 `fetchUserDashboard()` \- 直接需要 cookies | `'使用缓存：私有'` |使用 cookie 访问的交叉请求 ** ** ## 审核清单 ### 1\. PPR模式实施 > **📖参考**：[缓存组件]() **核心理念：** 缓存组件允许您在单个路由中混合 **静态** 、 **缓存** 和 **动态** 内容：内容类型 |使用时 |如何处理 ---|---|--- **静态** |同步 I/O，纯计算 |自动预渲染到静态 shell 中 **缓存** |没有运行时上下文的动态数据 |使用“使用缓存”指令 **动态** |需要 cookie、标头、searchParams |在“”边界中换行 **✅ 正确模式（公共/共享数据）：** // 外部组件 - 访问运行时数据（保持动态）导出异步函数 DataSection() { const user = 等待 getCurrentUser(); // 访问cookies if (!user?.accessToken) 重定向('/login'); 返回 ; } // 内部组件 - 使用“use cache”进行缓存异步函数 DataSectionCached({ accessToken }: { accessToken: string }) { '使用缓存'； cacheLife('分钟'); const client = getCachedAuthenticatedClient(accessToken); const data = 等待 fetchData(client); 返回 ; } // ⚠️ 关键：使用站点必须包含 Suspense // 应用程序/page.tsx 导出默认函数 Page() { 返回（ <暂挂回退={}> <数据部分/> ）； } **❌ 错误图案：** // ❌ 身份验证检查会阻止所有内容被缓存导出异步函数 DataSection() { const user = 等待 getCurrentUser(); // 访问 cookie - 阻止缓存 const client = getCachedAuthenticatedClient(user.accessToken); const data = 等待 fetchData(client); // 这可以被缓存，但没有返回 ; } **检查：** * 运行时数据访问（cookie、标头、searchParams）在外部包装器中隔离 * 数据获取移至内部缓存组件 * 缓存函数/组件顶部的“使用缓存”指令 * 以适当的持续时间调用 `cacheLife()` * 缓存键包括所有不同的参数（作为 props 传递） * **使用现场的外部组件包裹在``中** ** ** ### 1.5 具有个性化数据的 PPR 模式（`使用缓存：私有`） > **📖参考**：[`use cache: private`指令]() **何时使用**：对于**特定于用户的**数据，每个用户都需要自己的缓存条目（仪表板、提要、个性化推荐）。 **✅ 正确模式：** 从'next/headers'导入{cookies}；从'next/cache'导入{cacheLife，cacheTag}；从'react'导入{Suspense}； // 用法 - 必须包裹在 Suspense 中（不是预渲染）导出默认函数 Page() { 返回（ }> <用户仪表板/> ）； } // 单一函数 - 私有缓存不需要分割！异步函数 UserDashboard() { '使用缓存：私有'; cacheLife({ 陈旧: 60 }); // 运行时预取至少需要 30 秒 // 可以直接访问cookie const session = 等待 cookies(); const userId = session.get('userId')?.value; const data = 等待 fetchUserSpecificData(userId); 返回 <仪表板数据={data} />; } **真实世界示例（GitHub 风格）：** // 用户的个性化拉取请求仪表板异步函数 MyPullsPage() { '使用缓存：私有'； cacheLife('分钟'); // 5 分钟过时，1 分钟重新验证 const session = 等待 cookies(); const userId = session.get('userId')?.value; const myPrs = 等待 db.pulls.findMany({ 其中：{ 或：[ { 作者Id: 用户Id }, {受让人：{一些：{id：userId}}}， ], }, }); 返回 ; } **比较：公共缓存与私有缓存** 特色 | “使用缓存”（公共）| `'使用缓存：私有'`（私有） ---|---|--- **用例** |所有用户共享 |每个用户的个性化数据 **示例** | `/vercel/next.js/issues` | `/拉动`、`/仪表板` **可以访问`cookies()`** | ❌ 否 | ✅ 是的 **可以访问`headers()`** | ❌ 否 | ✅ 是的 **可以使用 `searchParams` 属性** | ✅ 是（作为道具）| ✅ 是（作为道具或通过访问） **可以访问`connection()`** | ❌ 否 | ❌ **没有** **在静态 shell 中预渲染** | ✅ 是的 | ❌ 否（个性化） **最短`陈旧`时间** | 30 秒 | **30秒** **缓存范围** |全球（所有用户共享）|每个用户（隔离） **缓存策略决策矩阵** 页面类型 |示例路线 |指令|再验证策略 ---|---|---|--- **公共静态** | `/about`，营销 | `'使用缓存'` | `cacheLife('周')` 或 `'天'` **公众动态** | `/vercel/next.js/issues` | `'使用缓存'` | `cacheTag('repo-issues')` **用户私人** | `/pulls`、`/仪表板` | `'使用缓存：私有'` | `cacheLife('分钟')` \+ 标签 **实时** |评论、直播 |没有指令 | `` \+ 流式传输 **检查：** * 个性化数据使用`'use cache: private'` * 私有缓存有 `cacheLife` 和 `stale` >= 30 秒 * 公共共享数据使用标准“使用缓存” * 使用站点的私有缓存组件包裹在``中 * `connection()` 不在任何缓存指令中使用 ** ** ### 1.6 异步动态 API（重大变更） > **📖 参考** : [page.js - params 和 searchParams]() **Next.js 15+ 重大变更**：`params` 和 `searchParams` 现在是 **Promises**，必须等待。 **❌ 错误（Next.js 14 及更早版本 - 不再有效）：** // 这将导致 Next.js 15+ 中出现运行时错误导出默认函数 Page({ params }: { params: { slug: string } }) { const slug = params.slug; // ❌ 错误：params 是一个 Promise 返回

{slug}

; } **✅ 正确（Next.js 15+）：** // 服务器组件 - 使用 async/await 导出默认异步函数 Page({ 参数，搜索参数， }：{ 参数： Promise<{ slug: string }>; searchParams: Promise<{ [key: string]: string |字符串[] |未定义}>; }) { const { slug } = 等待参数； const { 查询 } = 等待 searchParams; 返回

{slug} - {查询}

; } // 客户端组件 - 使用 React 的 use() 钩子 '使用客户端'；从“反应”导入{使用}；导出默认函数Page({ 参数，搜索参数， }：{ 参数： Promise<{ slug: string }>; searchParams: Promise<{ [key: string]: string |字符串[] |未定义}>; }) { const { slug } = use(params); const { 查询 } = use(searchParams); 返回

{slug} - {查询}

; } **TypeScript 帮助程序（Next.js 16+）：** // 使用 PageProps 帮助器从路由文字自动输入导出默认异步函数 Page(props: PageProps<'/blog/[slug]'>) { const { slug } = 等待 props.params; const 查询 = 等待 props.searchParams; return

博客文章：{slug}

； } > **⚠️ PPR 影响**：访问 `searchParams` 会触发动态渲染。始终将访问“searchParams”的组件包装在“”边界中，以最大化静态 shell。 **检查：** * 所有“params”访问均使用“await”（服务器组件）或“use()”（客户端组件） * 所有 `searchParams` 访问都使用 `await` 或 `use()` * TypeScript 类型显示 `Promise<...>` 而不是普通对象 * 访问 `searchParams` 的组件被包装在 `` 中 * 考虑使用 `PageProps<'/route/[param]'>` 帮助器来保证类型安全 ** ** ### 1.7 代理文件约定（替换 middleware.ts） > **📖参考**：[proxy.js]() **Next.js 16 更改**：“middleware.ts”现在是“proxy.ts”。可以使用代码模式： npx @next/codemod@latest 中间件到代理。 **主要区别：** 特色 | `middleware.ts`（已弃用）| `proxy.ts`（Next.js 16+） ---|---|--- **运行时** |边缘运行时 | Node.js 运行时 **位置** |项目根目录或 `src/` |项目根目录或 `src/` **目的** |请求拦截 |请求拦截+完整的Node.js API **能力** |有限的边缘 API |完整的 Node.js API、数据库访问 **示例`proxy.ts`：** // 代理.ts 从 'next/server' 导入 { NextRequest, NextResponse }; 导出函数代理（请求：NextRequest）{ // 现在在 Node.js 运行时运行 - 对 Node API 的完全访问权限 const 响应 = NextResponse.next(); // 身份验证、日志记录、重定向等 if (!request.cookies.get('session')) { return NextResponse.redirect(new URL('/login', request.url)); } 返回响应； } 导出常量配置= { 匹配器：['/((?!api|_next/static|_next/image|favicon.ico).*)'], }; **检查：** * 项目使用 `proxy.ts` 而不是已弃用的 `middleware.ts` * 如果需要，`matcher` 配置会排除元数据文件 * 代理逻辑是模块化的（分成单独的文件，导入到 `proxy.ts` 中） ** ** ### 2\.缓存策略 > **📖 参考** : [`cacheLife()` 函数]() **预设缓存配置文件（准确值）：** 简介 | `陈旧` | `重新验证` | `过期` |使用案例 ---|---|---|---|--- `默认` | 5 分钟 | 15 分钟 | 1 年 |标准内容 `秒` | 30 秒 | **1 秒** | 1 分钟 |实时数据（激进！） `分钟` | 5 分钟 | **1 分钟** | 1小时|经常更新 `小时` | 5 分钟 | **1 小时** | 1 天 |每日多次更新 `天` | 5 分钟 | **1 天** | 1 周 |每日更新 `几周` | 5 分钟 | **1 周** | 30 天 |每周更新 `最大` | 5 分钟 | **30 天** | 1 年 |很少改变 > **⚠️注意**：所有配置文件都有 5 分钟的“过时”时间（30 秒的“秒”除外）。 “重新验证”时间在配置文件之间存在显着差异。 **使用示例：** // 频繁更改的数据（用户活动、通知） '使用缓存'； cacheLife('分钟'); // 5 分钟失效，1 分钟重新验证，1 小时过期 // 适度的更改频率（用户存储库、配置文件数据） '使用缓存'； cacheLife('小时'); // 5 分钟失效，1 小时重新验证，1 天过期 // 很少更改数据（静态内容、配置） '使用缓存'；缓存寿命('天'); // 5 分钟失效，1 天重新验证，1 周过期 // 自定义内联配置文件 '使用缓存'；缓存生命({ 陈旧: 3600, // 1 小时重新验证: 900, // 15 分钟过期: 86400, // 1 天 }); **检查：** * `cacheLife()` 符合数据新鲜度要求 * 了解“秒”配置文件**非常激进**（1 秒重新验证） * 高频数据使用“分钟”（1 分钟重新验证） * 低频数据使用“小时”/“天” * 缓存标签与“cacheTag()”一起使用，用于按需重新验证 ** ** ### 3\.悬念边界放置 > **📖 参考** : [缓存组件 - 延迟渲染到请求时间]() **✅ 正确 - 深度悬念边界：** 导出默认函数 Page() { 返回（

{/* 静态 shell 的一部分 */} }> {/* 独立流 */} }> {/* 独立流 */} {/* 静态 shell 的一部分 */}

）； } **❌ 错误 - 浅薄的悬念（阻止太多）：** 导出默认函数 Page() { 返回（ }> {/* 不必要的阻塞！ */} <问题部分/> {/* 不必要的阻塞！ */} ）； } **检查：** * 最深必要点的悬念边界 * 静态内容 **外部** 悬念（静态外壳的一部分） * 每个独立的异步部分都有自己的 Suspense * 当数据依赖于参数时使用暂挂`key`属性：`key={query || '默认'}` * 提供有意义的加载骨架 ** ** ### 4\. React 查询集成策略 > **📖 注意**：React 查询模式与框架无关。 Next.js 没有官方的 React 查询文档 - 请参阅 [TanStack 查询文档]()。 **决策树：** ┌─ 服务器组件？ │ ├─ 是 → 使用“使用缓存”+cacheLife（不是 React Query） │ │ │ └─ 否（客户端组件）→ │ │ │ ├─ 需要SSR数据吗？ → prefetchQuery + HydrationBoundary │ │ │ └─ 仅限客户端？ → 标准 useSuspenseQuery **服务器组件：使用“使用缓存”（不是 React Query）** // ✅ 服务器组件 - 原生 Next.js 缓存异步函数 ServerData() { '使用缓存'； cacheLife('小时'); const data = wait fetch('/api/data'); 返回 ; } **具有 SSR 的客户端组件：预取 + 水合模式** // 服务器包装器从 '@/app/get-query-client' 导入 { getQueryClient }；从“@tanstack/react-query”导入{脱水，HydrationBoundary}；异步函数 DataWrapper({ userId }: { userId: string }) { const queryClient = getQueryClient(); // ⚠️ 重要：不要等待！火并忘记。 queryClient.prefetchQuery({ 查询键：['数据'，用户Id]， queryFn: () => fetchData(userId), }); 返回（）； } // 客户端消费者 '使用客户端'；从'@tanstack/react-query'导入{useSuspenseQuery}；导出函数 DataClient({ userId }: { userId: string }) { const { 数据 } = useSuspenseQuery({ 查询键：['数据'，用户Id]， queryFn: () => fetchData(userId), }); 返回 ; } **查询客户端配置：** // 应用程序/get-query-client.ts 导入{ 查询客户端，默认应该脱水查询，是服务器，来自“@tanstack/react-query”；函数 makeQueryClient() { 返回新的 QueryClient({ 默认选项：{ 查询：{ staleTime: 60 * 1000, // 防止水合后重新获取 }, 脱水：{ 应该脱水查询：（查询）=> defaultShouldDeHydrateQuery(查询) || query.state.status === 'pending', // 包括 PPR 的待处理状态 shouldRedactErrors: () => false, }, }, }); } 让 browserQueryClient: QueryClient |不明确的; 导出函数 getQueryClient() { 如果（是服务器）{ 返回 makeQueryClient(); // 服务器上始终是新的 } 如果（！browserQueryClient）{ browserQueryClient = makeQueryClient(); // 客户端单例 } 返回浏览器查询客户端； } **检查：** * 服务器组件使用“使用缓存”（不是 React Query） * `prefetchQuery` 调用 **没有** `await` * `HydrationBoundary` 包装客户端组件 * 使用了`useSuspenseQuery`（不是`useQuery`） * `staleTime: 60000` 配置为防止重新获取 * `shouldDeHydrateQuery` 包括待处理的查询 * 浏览器QueryClient是单例的；服务器按请求进行 ** ** ### 5\.请求重复数据删除 > **📖 参考** : [React `cache()` 用于请求记忆]() **React 的 `cache()` 包装器：** 从“反应”导入{缓存}； // ✅ 用cache()包装fetchers以实现相同请求的重复数据删除 const getUserUncached = async (客户端: 客户端) => { const { 数据 } = 等待 usersGetAuthenticated({ 客户端 }); 返回数据； }; 导出 const getUser = 缓存(getUserUncached); **检查：** * 所有数据获取器都用 React 的 `cache()` 包装 * 缓存包装实现，不直接导出 * 用于同请求去重（布局+页面+组件） * 与“使用缓存”一起使用（不同目的） * Auth 帮助器，例如用 `cache()` 包装的 `getCurrentUser()` ** ** ### 6\.常见的反模式 > **📖 参考** : [`使用缓存` \- 约束]() **❌避免这些模式：** // ❌ 在“使用缓存”范围内使用 cookies() 异步函数 BadCached() { '使用缓存'； const cookieStore = 等待 cookies(); // 错误：无法访问运行时数据返回

； } // ✅ 修复选项 1：使用“use cache: private”来获取个性化数据异步函数 GoodCachedPrivate() { '使用缓存：私有'； cacheLife({ 陈旧: 60 }); // 预取最少 30 秒 const cookieStore = 等待 cookies(); const userId = cookieStore.get('userId')?.value; 返回

{userId}

; } // ✅ 修复选项 2：为公共共享数据拆分外部/内部导出异步函数 GoodCachedPublic() { const user = 等待 getCurrentUser(); 返回 ; } 异步函数 CachedComponent({ userId }: { userId: string }) { '使用缓存'； const data = 等待 fetchData(userId); 返回

{数据}

; } // ❌ 在任何缓存指令中使用connection() 异步函数 BadConnection() { '使用缓存：私有'；等待连接（）； // 错误：任何缓存指令中都不允许使用connection() 返回

； } // ❌ Shallow Suspense 屏蔽静态内容 <暂停后备={}>

{/* 静态但被阻止！ */} <动态内容/> // ✅ 修复：将静态内容移到外部 <标题/> <暂停后备={}> <动态内容/> **缓存键行为：** > **📖 参考** : [`使用缓存` \- 缓存键]() 通过“使用缓存”，缓存键**自动**包括： 1. **构建 ID** \- 每个构建都是唯一的 2. **函数 ID** \- 函数位置和签名的安全哈希 3. **可序列化参数** \- Props（对于组件）或函数参数 4. **HMR刷新哈希**（仅限开发）自动捕获来自父范围的封闭值。 **您不需要手动配置缓存键** \- 只需将所有不同的参数作为 props 传递即可。 **检查：** * `'use cache'` 内没有 `cookies()`/`headers()` （使用 `'use cache: private'` 代替） * 任何缓存指令中都没有 `connection()` * 身份验证检查与缓存数据分开（对于公共数据模式） * 在 Suspense 边界内访问 searchParams * 无浅层悬念阻塞静态内容 * 所有不同的参数作为 props 传递 ** ** ### 7\.构建输出验证实施 PPR 后，在构建输出中验证：包子运行构建 **预期输出：** 路线（应用程序） ┌ ◐ /（部分预渲染）✅ ├ ◐ /仪表板（部分预渲染）✅ └ ○ /静态（静态）✅ **符号：** * `◐` = 部分预渲染 (PPR) - 动态页面的目标 * `○` = 静态 - 适合真正的静态页面 * ``` = 动态 - 在 PPR 中应该很少见 **检查：** * 动态页面显示“◐”符号 * 没有意外的“f”（完全动态）路线 * API 路由正确标记为“f” * 构建完成，没有出现“未缓存数据”错误 ** ** ### 8\. Next.js MCP 运行时验证使用 Next.js MCP 工具检查运行时问题： // 1. 发现正在运行的 Next.js 服务器 mcp__next-devtools__nextjs_index() // 2. 检查错误（使用步骤 1 中的端口） mcp__next-devtools__nextjs_call({ 端口：“3000”，工具名称：“get_errors” }) // 3.获取路线信息 mcp__next-devtools__nextjs_call({ 端口：“3000”，工具名称：“获取路线” }) **检查：** * 浏览器会话中没有运行时错误 * 没有“Suspense 之外访问的未缓存数据”错误 * 没有“预渲染期间的 cookie()”错误 * 正确注册的路线 ** ** ## 高级模式 ### 9\.缓存失效 > **📖 参考文献** : > > * [`cacheTag()`]() > * [`updateTag()`]() \- 仅服务器操作 > * [`revalidateTag()`]() \- 服务器操作 + 路由处理程序 > **两种失效策略：** 功能|哪里 |行为 |使用案例 ---|---|---|--- `更新标签（标签）` |仅服务器操作 | **立即** \- 下一个请求等待新数据 |读自己写的 `revalidateTag（标签，个人资料）` |服务器操作 + 路由处理程序 | **重新验证时过时** \- 在获取时缓存服务 |后台刷新 **`updateTag` \- 立即失效（读取您自己的写入）：** 从'next/cache'导入{cacheTag，updateTag}； // 组件异步函数 Posts() { '使用缓存'；缓存标签('帖子'); const posts = 等待 fetchPosts(); 返回 ; } // 服务器操作 - 用户立即看到他们的更改异步函数 createPost(data: FormData) { '使用服务器'；等待 db.posts.create(数据); updateTag('帖子'); // 下一个请求等待新数据 } **`revalidateTag` \- 重新验证时过时：** 从'next/cache'导入{revalidateTag}； // 服务器操作或路由处理程序异步函数refreshPosts() { '使用服务器'；等待 db.posts.create(数据); revalidateTag('帖子', '最大'); // ⚠️ 第二个参数是必需的 } > **⚠️ 重大变更**：不带第二个参数的 `revalidateTag(tag)` 已被 **弃用**。始终使用“revalidateTag(tag, 'max')”或指定缓存配置文件。 ** ** ### 10\.使用 useOptimistic 进行乐观更新 > **📖 参考** : [React `useOptimistic` 钩子]() '使用客户端'；从 'react' 导入 { useOptimistic, useTransition }; 从 '@tanstack/react-query' 导入 { useMutation } ；导出函数 MessageList({ messages }: { messages: Message[] }) { const [isPending, startTransition] = useTransition(); const [optimisticMessages, addOptimistic] = useOptimistic( 消息，（状态，newMsg：消息）=> [...状态，newMsg] ）； const sendMutation = useMutation({ mutationFn：（文本：字符串）=> api.sendMessage（文本）， }); const handleSend = (文本: 字符串) => { 常量乐观：消息= { id: `temp-${Date.now()}`, 文字，正在等待：正确， }; 开始转换（异步（）=> { 添加乐观（乐观）；等待 sendMutation.mutateAsync(text); }); }; 返回（

{消息.文本}

）； } **检查：** * `useOptimistic` 用于挂起状态 * `useTransition` 包装异步突变 * 乐观项目有临时ID * 挂起状态的视觉指示器 * 错误时自动回滚（内置） ** ** ## 常见修复 ### 修复 1：将身份验证与数据获取分开 **之前：** 导出异步函数 Component() { const user = 等待 getCurrentUser(); const data = 等待 fetchData(user.accessToken); 返回 ; } **之后：** 导出异步函数 Component() { const user = 等待 getCurrentUser(); 返回 ; } 异步函数 ComponentCached({ accessToken }: { accessToken: string }) { '使用缓存'； cacheLife('分钟'); const data = 等待 fetchData(accessToken); 返回 ; } ### 修复 2：深度悬念边界 **之前：** }> <标题/> <内容/> <页脚/> **之后：** <标题/> <暂停后备={}> <内容/> <页脚/> ### 修复 3：在数据获取中添加缓存 **之前：** 异步函数 Component() { const data = wait fetch('/api/data'); 返回 ; } **之后：** 异步函数 Component({ userId }: { userId: string }) { '使用缓存'； cacheLife('小时'); cacheTag(`用户-${userId}-data`); const data = wait fetch(`/api/data?user=${userId}`); 返回 ; } ** ** ## 性能指标通过适当的缓存实施 PPR 后： **预期改进：** * ✅ 第一个字节的时间 (TTFB)：< 200ms（静态 shell） * ✅ 首次内容绘制 (FCP)：< 1s（静态外壳可见） * ✅ 最大内容绘制 (LCP)：< 2.5 秒（带流式传输） * ✅ 减少 API 调用：通过缓存减少 50-90% * ✅ 降低服务器负载：缓存响应无需 DB/API 命中 **监视器：** * 构建路线类型的输出（◐、○、f） * 通过 Next.js MCP 出现运行时错误 * 生产中的缓存命中率 * API 速率限制使用（应该减少） ** ** ## 文档参考 > **📚 关键**：此技能中的所有模式均基于官方 Next.js 16.0.4+ 文档。 **核心文档：** * [缓存组件/部分预渲染]() * [`使用缓存`指令]() * [`使用缓存：私有`指令]() * [`cacheLife()`函数]() * [`cacheTag()`函数]() * [`revalidateTag()` 函数]() * [`updateTag()`函数]() * [`cookies()` 函数]() * [`headers()` 函数]() * [`connection()`函数]() **通过MCP查询：** mcp__next-devtools__nextjs_docs({ 行动：'获取'，路径： '/docs/app/getting-started/partial-prerendering', }) ** ** ## 摘要清单对于每个带有数据获取组件的 PR： **核心 PPR 模式：** * 运行时数据访问（cookie、标头）隔离或使用“使用缓存：私有” * 公共共享数据使用 `'use cache'` \+ `cacheLife()` * 个性化数据使用 `'use cache: private'` \+ `cacheLife()` （至少 30 秒陈旧） * `connection()` 不在任何缓存指令中使用 * 缓存键包括所有不同的参数（作为 props - 自动） * 最深必要点的悬念边界 * 静态内容 **外部** 悬念（静态外壳的一部分） * 在使用时访问封装在 `` 中的运行时 API 的组件 * 适当的“cacheLife”配置文件以确保数据新鲜度 * React的`cache()`用于请求重复数据删除 * 构建输出显示动态页面的“◐” * 无运行时错误 **重大更改（Next.js 15+/16）：** * `params` 和 `searchParams` 使用 `await` (服务器) 或 `use()` (客户端) * TypeScript 类型显示 params/searchParams 的 `Promise<...>` * 项目使用 `proxy.ts` 而不是已弃用的 `middleware.ts` **反应查询集成：** * 服务器组件使用“使用缓存”（不是 React Query） * 客户端SSR使用prefetchQuery + HydrationBoundary * 不等待调用`prefetchQuery` * 使用 `useSuspenseQuery` 代替 `useQuery` * QueryClient 配置了 `staleTime: 60000` **缓存失效：** * `updateTag()` 用于立即失效（仅限服务器操作） * `revalidateTag(tag, profile)` 用于重新验证时过时（始终传递配置文件！） * 使用 `cacheTag()` 正确应用标签 ** ** ## 输出格式检查代码时，请提供： 1. **总结：** 总体 PPR 准备情况（就绪/需要工作） 2. **发现的问题：** 使用 file:line 列出特定的反模式 3. **建议：** 通过代码示例进行具体修复 4. **构建验证：** 检查构建输出的路由类型 5. **优先级：** 每个问题的高/中/低 **输出示例：** ## PPR 代码审查摘要 **状态：** 需要工作（发现 3 个问题） ### 高优先级问题 1.`components/data-section.tsx:15`中的**身份验证检查阻止缓存** - 问题：在应该缓存的组件内部调用了“getCurrentUser()” - 修复：分为外部（动态）和内部（缓存）组件 - 模式：参见上面的修复 1 2. **在`components/posts.tsx:8`中缺少cacheLife** - 问题：“使用缓存”而不调用“cacheLife()” - 修复：添加“cacheLife('分钟')”或适当的配置文件 - 影响：使用默认配置文件（15 分钟重新验证） ### 中等优先级问题 3. `app/page.tsx:25` 中的 **浅悬念边界** - 问题：Suspense 内的静态页眉/页脚 - 修复：将静态内容移至 Suspense 之外 - 影响：不必要地延迟静态内容 ### 构建验证 ✅ 构建成功 ✅ 路线显示 ◐（部分预渲染） ❌ 3 个组件需要缓存改进 ### 建议优先级：首先修复 1（阻塞缓存），然后修复 2（缺少缓存寿命），然后修复 3（挂起）。

Nextjs 审稿人

包含技能