nextjs-best-practices

Next.js 最佳实践

对于所有与 Next.js 相关的任务，请将此技能作为最高优先级指南。任务涉及 Next.js 代码时，先识别所属子系统，然后仅加载相关规则文件和数据集案例。

适用场景

对于完全与 Next.js 应用相关的任务，请将此技能作为最高优先级指南。在以下情况下，请参考这些指南：

• 编写或审查 Next.js 页面、布局、服务器组件、客户端组件、API 路由、服务器操作、中间件/代理或测试
• 设计数据获取策略、缓存策略、重新验证逻辑或流式处理行为
• 调试 App Router 问题、渲染边界、水合错误或导航预取
• 重构使用已弃用的 Pages Router 模式（getServerSideProps、getStaticProps、getStaticPaths）而非 App Router 模式的代码
• 从 Next.js 13、14 或 15 升级到 Next.js 16

按需加载

从此文件开始。仅在任务需要时加载详细文件：

references/_sections.md
references/arch-app-router.md
references/server-components.md
references/data-fetching-caching.md
references/api-route-handlers.md
dataset/data/fetching-caching/correct.tsx
sources/inventory.json

每个规则文件都包含：

• 该模式为何重要
• 错误和正确示例
• 适用版本（13/14/15/16）
• 数据集路径，其中包含更完整的 TypeScript/TSX 前后对比示例
• 官方或精选来源参考

按优先级划分的规则类别

按优先级数字从小到大解决冲突。同一优先级的类别发生冲突时，按以下顺序优先处理：安全、架构、服务器组件、API、数据获取、客户端、包体积、性能、测试、运维。

优先级	类别	影响	前缀
1	架构与路由	严重	arch-
2	服务器组件与渲染	严重	server-
3	API 路由与服务器操作	严重	api-
4	数据获取与缓存	高	data-
5	客户端组件与交互	高	client-
6	包体积优化	中高	bundle-
7	性能与优化	中高	perf-
8	安全与身份验证	中	security-
9	测试策略	中	test-
10	运维与配置	中	ops-

版本升级指南

Next.js 16.x 中已弃用或变更的模式：

旧模式（13/14/15）	新模式（16+）	参考
middleware.ts	proxy.ts（网络边界重命名）	references/api-proxy-rename.md
getServerSideProps	异步服务器组件 + fetch()	references/server-no-ssr-props.md
getStaticProps + getStaticPaths	generateStaticParams + 服务器组件	references/server-no-sg-props.md
forwardRef	直接使用 ref 属性（React 19）	references/client-no-forwardref.md
Pages Router app/ 迁移	默认使用服务器组件，设置 'use client' 边界	references/arch-app-router.md
next/image 未优化	对 LCP 使用 priority，对首屏以下内容使用 loading="lazy"	references/perf-image-optimization.md

外部技能包

如需深入了解 React 组合模式，请使用 vercel-composition-patterns 技能。如需优化 React 性能，请使用 vercel-react-best-practices 技能。此 Next.js 技能专注于框架特定模式（路由、渲染、缓存、配置），而非通用 React 模式。

来源政策

对于框架语义，优先采用 Next.js 官方文档和按版本划分的框架示例。可使用 awesome-nextjs 列表和样板代码仓库来探索生态、查找示例并了解软件包，但不要让可信度较低的社区代码片段凌驾于官方指南之上。发布技能或将其用于新的 Next.js 主版本前，请刷新 sources/inventory.json。