该技能用于在 Next.js 项目(重点是 App Router)中给出符合当前版本的最佳实践建议。它以项目实际安装的 Next.js 版本为准,基线参考 Next.js 16.3.3 稳定文档,但项目本地、与版本匹配的文档优先。
用途:在提出代码前,先读 package.json、锁文件、next.config.* 及相关 app/ 或 pages/ 文件;若存在则遵循仓库 AGENTS.md 中 Next.js 管理块,并阅读 node_modules/next/dist/docs/ 对应文档;确认 cacheComponents 与 partialPrefetching 是否启用,因为它们会显著改变缓存、预渲染与 <Link> 行为;保留现有路由器,除非任务要求,否则不要从 Pages Router 迁移到 App Router;canary 与 experimental.* 视为需主动开启,不因最新文档存在就启用。
主要能力:区分 cacheComponents 关闭与开启两种缓存模型。关闭时 dynamic、revalidate、fetchCache 仍有效;开启时数据默认动态,请求时工作用 <Suspense>,缓存工作用 'use cache' 配合 cacheLife/cacheTag,并移除 dynamic、revalidate、fetchCache,且需 Node.js 运行时。若同时开启 partialPrefetching,每条路由获得可复用 App Shell,依赖 params 或 searchParams 的 URL 特定工作应置于 <Suspense> 之后,除非链接有意预取。决策规则包括:优先服务端组件,仅在最小边界加 'use client';机密与特权数据访问留在仅服务端模块,Server Actions 是可达的 POST 入口,必须做认证、授权与校验;在服务端组件中 await params、searchParams、cookies()、headers();用 useActionState 处理结果与待定状态,useOptimistic 处理可逆乐观 UI;读己所写用 updateTag,stale-while-revalidate 用 revalidateTag(tag, 'max');16.3 中 error.tsx 优先用 retry(),组件级边界用 next/error 的 catchError,仅在确不需重取时用 reset();root 参数仅用于根布局之上且来自服务端组件。
验证:使用项目包管理器与现有脚本,先跑窄范围测试或类型检查,阅读 next dev 或 next build 诊断,在真实浏览器中验证加载、错误、导航与变更状态;对即时导航,在生产加载外壳中显式检查或测试,不能仅凭代码判断。
限制:资料未提供安装命令、价格、平台支持或具体代码示例;各项规则以项目本地版本匹配文档为准。