nextjs

Next.js Community Next.js 16 App Router 最佳实践

为 Next.js 16 App Router 应用提供的全面性能优化指南，由 Next.js Community 维护。包含 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 - 为图标库配置 optimizePackageImports
• build-dynamic-imports - 对大型组件使用动态导入
• build-barrel-files - 在 App Router 中避免从 Barrel 文件导入
• build-turbopack-config - 启用 Turbopack 文件系统缓存
• build-external-packages - 为 Node 依赖配置服务器外部包

2. 缓存策略（严重）

• cache-use-cache-directive - 使用 'use cache' 指令显式缓存
• cache-revalidate-tag - 将 revalidateTag 与 cacheLife 配置文件搭配使用
• cache-fetch-options - 正确配置 Fetch 缓存选项
• 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