nextjs

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

面向 Next.js 16 App Router 应用的全面性能优化指南，由 Next.js Community 维护。包含 8 个类别的 42 条规则，并按影响程度排序，用于指导自动重构和代码生成。其中两条规则介绍了 Next.js 16.3 预览功能（即时导航、部分预取），需启用 cacheComponents 和 partialPrefetching。

适用场景

在以下情况中参考这些指南：

• 编写新的 Next.js 16 App Router 代码
• 使用 'use cache' 指令配置缓存策略
• 实现服务端组件和数据获取
• 使用并行路由和拦截路由设置路由
• 创建用于表单处理和数据变更的服务端操作

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	构建与打包优化	CRITICAL	build-
2	缓存策略	CRITICAL	cache-
3	服务端组件与数据获取	HIGH	server-
4	路由与导航	HIGH	route-
5	服务端操作与数据变更	MEDIUM-HIGH	action-
6	流式传输与加载状态	MEDIUM	stream-
7	元数据与 SEO	MEDIUM	meta-
8	客户端组件	LOW-MEDIUM	client-

快速参考

1. 构建与打包优化（CRITICAL）

• build-optimize-package-imports - 为图标库配置 optimizePackageImports
• build-dynamic-imports - 对大型组件使用动态导入
• build-barrel-files - 在 App Router 中避免从 Barrel 文件导入
• build-turbopack-config - 在顶层配置 Turbopack
• build-external-packages - 为 Node 依赖配置服务端外部包

2. 缓存策略（CRITICAL）

• cache-use-cache-directive - 在 Cache Components 中使用 'use cache'
• cache-revalidate-tag - 将 revalidateTag 与 cacheLife 配置文件搭配使用
• cache-fetch-options - 明确配置 Fetch 缓存选项
• cache-revalidate-path - 使用 revalidatePath 使路由级缓存失效
• cache-react-cache - 使用 React cache() 去重请求
• cache-segment-config - 使路由配置与当前缓存模型相匹配

3. 服务端组件与数据获取（HIGH）

• server-parallel-fetching - 在服务端组件中并行获取数据
• server-component-streaming - 流式传输服务端组件，实现渐进式加载
• server-data-colocation - 将数据获取逻辑与组件放在一起
• server-preload-pattern - 对关键数据使用预加载模式
• server-avoid-client-fetching - 避免在客户端获取初始数据
• server-error-handling - 妥善处理服务端组件错误

4. 路由与导航（HIGH）

• route-parallel-routes - 使用并行路由呈现相互独立的内容
• route-intercepting-routes - 使用拦截路由实现模态框模式
• route-prefetching - 合理配置 Link 预取
• route-instant-navigations - 使用流式传输、缓存或阻塞实现即时导航（16.3 预览）
• route-partial-prefetching - 使用部分预取实现可复用的路由外壳（16.3 预览）
• route-proxy-ts - 使用 proxy.ts 处理网络边界逻辑
• route-not-found - 使用 notFound() 处理缺失资源

5. 服务端操作与数据变更（MEDIUM-HIGH）

• 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 - 高效加载第三方脚本

使用方法

先在项目根目录中运行：

npx -y @pymodel/react-frontend-skills detect               # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill nextjs  # deprecated APIs → rule IDs

对于上面与任务匹配的每条规则，以及每个 scan 命中项，请阅读 references/<rule-id>.md，了解其重要性，然后查看错误与正确的代码示例。

相关技能

• React 19 基础知识，请参阅 react 技能
• 数据获取模式，请参阅 tanstack-query 技能
• 客户端表单，请参阅 react-hook-form 技能