name: nextjs description: Next.js 16 App Router 性能优化指南（原 nextjs-16-app-router）。此技能应在编写 Next.js 16 代码、配置缓存、在 Next.js 中实现服务器组件、设置 App Router 路由或配置 next.config.js 时使用。此技能不涵盖通用 React 19 模式（使用 react-19 技能）或非 Next.js 的服务器渲染。
Next.js 社区 Next.js 16 App Router 最佳实践
为 Next.js 16 App Router 应用程序提供的全面性能优化指南，由 Next.js 社区维护。包含 8 个类别中的 40 条规则，按影响优先级排序，以指导自动重构和代码生成。
何时应用
在以下情况参考这些指南：
- 编写新的 Next.js 16 App Router 代码
- 使用 ‘use cache’ 指令配置缓存策略
- 实现服务器组件和数据获取
- 设置并行和拦截路由
- 创建用于表单处理和变异的服务器动作
规则类别按优先级
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 构建与打包优化 | 关键 | build- |
| 2 | 缓存策略 | 关键 | cache- |
| 3 | 服务器组件与数据获取 | 高 | server- |
| 4 | 路由与导航 | 高 | route- |
| 5 | 服务器动作与变异 | 中高 | action- |
| 6 | 流式与加载状态 | 中 | stream- |
| 7 | 元数据与 SEO | 中 | meta- |
| 8 | 客户端组件 | 低中 | client- |
快速参考
1. 构建与打包优化（关键）
build-optimize-package-imports- 为图标库配置 optimizePackageImportsbuild-dynamic-imports- 对重型组件使用动态导入build-barrel-files- 避免在 App Router 中使用桶文件导入build-turbopack-config- 启用 Turbopack 文件系统缓存build-external-packages- 为 Node 依赖配置服务器外部包
2. 缓存策略（关键）
cache-use-cache-directive- 使用 ‘use cache’ 指令进行显式缓存cache-revalidate-tag- 使用 revalidateTag 和 cacheLife 配置文件cache-fetch-options- 正确配置获取缓存选项cache-revalidate-path- 使用 revalidatePath 进行路由级缓存失效cache-react-cache- 使用 React cache() 进行请求去重cache-segment-config- 通过导出配置路由段缓存
3. 服务器组件与数据获取（高）
server-parallel-fetching- 在服务器组件中并行获取数据server-component-streaming- 流式传输服务器组件以实现渐进加载server-data-colocation- 将数据获取与组件共置server-preload-pattern- 对关键数据使用预加载模式server-avoid-client-fetching- 避免初始数据的客户端获取server-error-handling- 优雅地处理服务器组件错误
4. 路由与导航（高）
route-parallel-routes- 使用并行路由处理独立内容route-intercepting-routes- 使用拦截路由实现模态模式route-prefetching- 适当配置链接预取route-proxy-ts- 使用 proxy.ts 处理网络边界逻辑route-not-found- 使用 notFound() 处理缺失资源
5. 服务器动作与变异（中高）
action-server-action-forms- 使用服务器动作处理表单提交action-pending-states- 使用 useFormStatus 显示待处理状态action-error-handling- 优雅地处理服务器动作错误action-optimistic-updates- 使用乐观更新提供即时反馈action-revalidation- 变异后重新验证缓存
6. 流式与加载状态（中）
stream-suspense-boundaries- 战略性地放置 Suspense 边界stream-loading-tsx- 使用 loading.tsx 处理路由级加载状态stream-error-tsx- 使用 error.tsx 处理路由级错误边界stream-skeleton-matching- 使骨架尺寸与实际内容匹配stream-nested-suspense- 嵌套 Suspense 以实现渐进披露
7. 元数据与 SEO（中）
meta-generate-metadata- 使用 generateMetadata 生成动态元数据meta-sitemap- 动态生成站点地图meta-robots- 配置 robots 以控制爬取meta-opengraph-images- 生成动态 OpenGraph 图像
8. 客户端组件（低中）
client-use-client-boundary- 最小化 ‘use client’ 边界范围client-children-pattern- 将服务器组件作为子组件传递给客户端组件client-hydration-mismatch- 避免水合不匹配client-third-party-scripts- 高效加载第三方脚本
如何使用
阅读单个参考文件以获取详细解释和代码示例：
- 部分定义 - 类别结构和影响级别
- 规则模板 - 添加新规则的模板
- build-dynamic-imports - 示例规则文件
- cache-use-cache-directive - 示例规则文件
相关技能
- 对于 React 19 基础，参见
react-19技能 - 对于数据获取模式，参见
tanstack-query技能 - 对于客户端表单，参见
react-hook-form技能
完整编译文档
对于包含所有规则扩展的完整指南：AGENTS.md