nextjs

Next.js 16 App Router 最佳实践

面向 AI Agent 的 Next.js 16 App Router 综合指南。包含 9 个类别中的 45 条规则，按影响程度排序，涵盖从关键问题（构建优化、缓存策略）到跨领域代码库规范（去重、无用路由、边界一致性）。反映 Next.js 16 的变化：用 'use cache' 指令取代隐式缓存，revalidateTag(tag, cacheLife) 的要求，用 proxy.ts 取代 middleware.ts，Turbopack 持久化缓存，以及 App Router 约定。

规则文件描述的是模式形式（而非 API 名称），并以 “识别模式” 部分开篇，列出同一种问题可能呈现的 2–4 种语法伪装。部分高价值规则（其伪装在实践中最常见的规则——'use cache'、并行获取、动态导入、Server Action 表单、客户端边界、服务端与客户端获取）还包含一组具体的**“伪装示例”**错误/正确示例，帮助读者掌握 grep 难以发现的模式。

适用场景

• 编写新的 Next.js 16 App Router 代码
• 审查或现代化改造 Next.js 代码库——单个文件、PR 或整个仓库（参见 references/_review-algorithm.md）
• 从 Next.js 15 迁移到 16（隐式缓存 → 'use cache'，middleware.ts → proxy.ts，revalidateTag 从单参数改为带 cacheLife）
• 使用 'use cache'、unstable_cache、revalidateTag、revalidatePath 配置缓存策略
• 实现 Server Components 和并行/就近的数据获取
• 配置并行路由、拦截路由、预取和 proxy.ts
• 创建用于表单处理和数据变更的 Server Actions
• 调整 'use client' 边界，以尽可能缩小客户端包
• 发现代码库级问题，此类问题无法通过单文件规则发现：重复的服务端数据获取函数、近似重复的路由/布局、无用路由、'use client' 在路由树中的传播、属性形状偏移（参见类别 9）

如何审查或重构代码库

当用户要求审查、重构、现代化改造或审计 Next.js 代码（单个文件或整个仓库）时，请遵循 references/_review-algorithm.md。不要自行发挥。

该文档中的四项硬性要求：

1. 两种模式——绝不拒绝审计整个仓库。 选择 模式 A（限定范围，≤~20 个文件）或 模式 B（整个目录树：清点 + 定向扫描 + 完整类别 9）。
2. 判断优先于 grep。 每条规则描述的是一种模式形式，而非语法标记。扫描前请阅读每条规则的 “识别模式” 部分——grep 能找到容易发现的违规项，却会漏掉高价值问题（为了一个按钮而标记为 'use client' 的布局；使用 TanStack Query 获取初始页面数据；由路由处理程序承担 Server Action 的工作；手写缓存层来仿照 'use cache'；隐藏在父/子 Server Components 中的顺序获取）。
3. 按类别扫描，而非按文件扫描——并设置强制检查机制。 按优先级（CRITICAL → … → CROSS-CUTTING）一次扫描一个类别，覆盖所有纳入范围的文件。该算法要求提供范围声明、每个类别的进度行，以及最终的覆盖情况表（类别 × 文件/分组，单元格取值 ∈ {clean, N findings, n/a}）。输出中缺少某个类别会立即显现。
4. 代码库级问题来自类别 9。 单文件规则无法告诉你“这两个路由应该合并”或“这个服务端操作已经无用”。类别 9（代码库规范）会在最后扫描完整清单，并给出删除/去重/复用/整合方面的发现。

单文件的临时问题（例如“这个缓存策略对吗？”）可以直接查看相关规则。该算法适用于涉及多个文件或整个仓库的情况。

规则类别

#	类别	影响	规则	主要主题
1	构建与打包优化	严重	5	Turbopack、optimizePackageImports、动态导入、barrel 文件、serverExternalPackages
2	缓存策略	严重	6	'use cache'、revalidateTag+cacheLife、fetch 选项、段配置
3	服务端组件与数据获取	高	6	并行获取、流式传输、共置、预加载、避免客户端获取、错误处理
4	路由与导航	高	5	并行路由、拦截路由、预取、proxy.ts、notFound()
5	服务端操作与变更	中高	5	服务端操作、useFormStatus、操作结果错误、useOptimistic、重新验证
6	流式传输与加载状态	中	5	Suspense 放置、loading.tsx、error.tsx、骨架屏匹配、嵌套 Suspense
7	元数据与 SEO	中	4	generateMetadata、sitemap.ts、robots.ts、opengraph-image.tsx
8	客户端组件	低中	4	'use client' 边界、children 模式、水合不匹配、next/script
9	代码库整洁性	低中	5	去重服务端数据获取器、整合路由、清理无用路由/操作、'use client' 传播、属性漂移

快速参考

关键模式——首先确保这些做法正确：

• 对结果应缓存的服务端组件/函数添加 'use cache'（Next.js 16 移除了隐式 fetch 缓存）
• 调用 revalidateTag(tag, cacheLife) 并指定配置文件——不要使用单参数 API
• 为导出结构扁平的图标/实用工具库配置 optimizePackageImports
• 不要禁用 Turbopack 持久缓存
• 使用 <form action={serverAction}>，而不是向 /api/... 发送 POST 请求

Next.js 16 惯用写法（不要生成 Next.js 15 的模式）：

• proxy.ts（Node 运行时）——不要使用 middleware.ts（Edge）
• 显式使用 'use cache'——不要依赖隐式 fetch 缓存
• revalidateTag(tag, cacheLife)——不要使用单参数 revalidateTag(tag)
• 服务端操作 + useActionState——不要使用客户端 fetch + useState
• app/sitemap.ts——不要手动维护 public/sitemap.xml

常见的单文件错误——避免这些反模式：

• 对彼此独立的数据按顺序使用 await（应使用 Promise.all 或预加载）
• 在客户端组件中使用 useEffect + fetch 获取初始页面数据
• 为了一个可交互按钮就在布局层级添加 'use client'
• 执行会更改数据的服务端操作后，未调用 revalidatePath/revalidateTag
• 骨架屏尺寸与内容不匹配（导致 CLS 问题）

代码库级模式——在类别 9 的检查中关注这些情况：

• 2 个或更多服务端组件请求同一上游服务，但缓存策略各不相同——提取为共享的缓存数据获取器
• 2 个或更多几乎重复的路由/布局本应通过变体或动态段合并为一个——整合
• 90 天或更久没有入站流量的路由/路由处理程序/服务端操作——删除（先检查分析数据）
• 因一个可交互叶节点而导致 'use client' 沿路由树向上传播——将布局/父级降级为服务端组件，仅保留一个客户端岛
• 同一概念使用了不同的路由参数/搜索参数/属性名称——统一为规范名称（注意 SEO 重定向）

目录

1. 构建与打包优化 — CRITICAL
   • 1.1 从源模块导入，而不是从聚合文件 index.ts 导入 — CRITICAL（开发启动速度提升 2-10 倍）
   • 1.2 在 optimizePackageImports 中声明扁平导出包 — CRITICAL（导入速度提升 200-800 毫秒，打包体积缩小 50-80%）
   • 1.3 将带有原生绑定的 Node 包标记为 serverExternalPackages — HIGH
   • 1.4 不要禁用 Turbopack 的持久化缓存 — CRITICAL（冷启动速度提升 5-10 倍）
   • 1.5 将大型组件拆分为单独加载的代码块 — CRITICAL（初始打包体积缩小 30-70%）
2. 缓存策略 — CRITICAL
   • 2.1 为每个服务端 fetch 声明缓存意图 — HIGH
   • 2.2 通过分段配置导出声明路由级缓存 — MEDIUM-HIGH
   • 2.3 使用 'use cache' 显式标记可缓存的服务端组件/函数 — CRITICAL
   • 2.4 调用带有配置文件的 revalidateTag(tag, cacheLife) — CRITICAL
   • 2.5 每个会修改数据的 Server Action 都必须使展示该数据的路由/标签失效 — HIGH
   • 2.6 使用 React cache() 包装每请求调用的 fetcher，以去重请求 — HIGH
3. 服务端组件与数据获取 — HIGH
   • 3.1 彼此独立的服务端 fetch 应并发运行——顺序执行 await 会形成瀑布流 — HIGH
   • 3.2 为每个节奏独立的异步叶节点分别包裹 <Suspense> — HIGH
   • 3.3 每个 Server Component 都应获取其所渲染的数据 — HIGH
   • 3.4 通过 preload 调用，在顶部触发关键数据获取 — MEDIUM-HIGH
   • 3.5 初始页面数据应通过 Server Component 写入 HTML——绝不要使用 useEffect+fetch — MEDIUM-HIGH
   • 3.6 通过 error.tsx 或 ErrorBoundary 捕获异步错误 — MEDIUM
4. 路由与导航 — HIGH
   • 4.1 多区域布局使用并行路由插槽 — HIGH
   • 4.2 模态框/灯箱详情视图使用拦截路由 — HIGH
   • 4.3 根据流量可能性调整 <Link prefetch> — MEDIUM-HIGH
   • 4.4 网络边界逻辑应放在 proxy.ts 中，而不是 middleware.ts — MEDIUM-HIGH
   • 4.5 缺失的动态资源应调用 notFound()，以返回真正的 HTTP 404 — MEDIUM
5. Server Action 与数据修改 — MEDIUM-HIGH
   • 5.1 表单提交触发的数据修改应通过 Server Action 执行，而不是使用 API 路由 + 客户端 fetch — MEDIUM-HIGH
   • 5.2 提交按钮通过 useFormStatus 读取父表单的待处理状态 — MEDIUM-HIGH
   • 5.3 Server Action 应返回类型化的错误/状态结果——绝不要静默抛出异常 — MEDIUM-HIGH
   • 5.4 对于 UI 结果可预测的数据修改，应采用乐观更新 — MEDIUM
   • 5.5 每个 Server Action 都应使展示其数据的路由/标签失效 — MEDIUM
6. 流式传输与加载状态 — MEDIUM
   • 6.1 在节奏独立的子树周围放置 Suspense — MEDIUM
   • 6.2 每个路由都应在其 page.tsx 旁边放置 loading.tsx — MEDIUM
   • 6.3 每个路由旁边都应放置 error.tsx — MEDIUM
   • 6.4 骨架屏应与其所替代内容的尺寸一致 — MEDIUM
   • 6.5 内容有自然的显示顺序时，应嵌套使用 Suspense — LOW-MEDIUM
7. 元数据与 SEO — MEDIUM
   • 7.1 动态路由应导出 generateMetadata，为每项资源生成 SEO 元数据 — MEDIUM
   • 7.2 根据实际数据生成站点地图——绝不要手动维护 XML — MEDIUM
   • 7.3 通过 app/robots.ts 和每页元数据明确声明爬取规则 — MEDIUM
   • 7.4 通过 opengraph-image.tsx 为每个页面生成 OG 图片 — LOW-MEDIUM
8. 客户端组件 — LOW-MEDIUM
   • 8.1 将 'use client' 下移到交互式叶节点 — LOW-MEDIUM
   • 8.2 服务端内容通过 children 传入 Client Component 内部 — LOW-MEDIUM
   • 8.3 SSR 与客户端的初始渲染必须生成相同的 HTML — LOW-MEDIUM
   • 8.4 使用 next/script 包装第三方脚本，并设置正确的 strategy — LOW-MEDIUM
9. 代码库规范 — CROSS-CUTTING（涉及多个文件的问题；全仓库审计必查）
   • 9.1 将重复的服务端 fetcher/action 提取到共享模块中 — HIGH
   • 9.2 整合高度相似的路由/布局/组件 — HIGH
   • 9.3 删除无法访问的路由、未使用的 Server Action 和孤立工具函数 — MEDIUM-HIGH
   • 9.4 审查整个路由树中的 'use client' 放置位置 — HIGH
   • 9.5 统一路由/组件中同一概念的规范名称 — MEDIUM-HIGH

参考资料

1. Next.js 文档
2. Next.js 16 发布说明
3. React 文档
4. Vercel 工程博客

相关技能

• 关于 React 19 基础知识（并发渲染、hooks、组件），请参阅 react 技能
• 关于客户端表单处理，请参阅 react-hook-form 技能
• 关于使用 TanStack Query 缓存客户端数据，请参阅 tanstack-query 技能

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md