如何用 AI 写对 Next.js 代码

App Router 的坑，为什么不容易自己发现

Next.js 进入 App Router 时代后，许多问题不是"报错"，而是"写法不符合框架预期"。服务端组件和客户端组件的边界没划清，可能引出 hydration 错误或把不该上客户端的逻辑带过去；数据获取顺序没排好，一串串行请求拖成水瀑式加载；升级到 Next.js 15 后，params、cookies、headers 变成异步 API，旧写法会冒出构建警告和运行时报错；metadata、OG 图、图片字体优化和自托管部署各有约定，稍不留意就偏离规范。这些坑往往要等性能下滑或线上异常才暴露。

这个技能怎么帮你写对 Next.js

它是一套规则型指南，按主题进入对应参考文档，专门识别 Next.js 项目里的风险模式并给出符合版本特性的修正。文件约定方面，梳理特殊文件和路由段的组织规则，统一目录结构与命名。边界方面，检查 RSC 边界、客户端组件和 Server Action 的使用风险，是处理 hydration 错误的关键。迁移方面，指导异步 params、cookies、headers 等新 API 的正确写法，避免升级后构建警告与运行时报错。优化方面，提供图片、字体、脚本、打包和自托管的准则。它的定位是"审查与重构"——告诉你哪里写得不对、该怎么改，而非替你从零搭项目。

怎么用它

用法是把要审查或重构的 Next.js 代码、要解决的问题用自然语言说清楚，由它对照规范给出修正。例如可以这样对它说：

它适合这些场景：新建 Next.js 应用时统一目录结构、路由命名和特殊文件放置；审查 App Router 项目中服务端组件、客户端组件和数据流边界；升级 Next.js 15+ 后处理异步 API、元数据和错误页面变化；定位 hydration 错误、打包异常、图片字体加载或自托管部署问题。

大家常问

在 Next.js 里，服务端组件和客户端组件到底有什么区别？

App Router 里组件默认是服务端组件（RSC），可直接 async 取数、查数据库、不打进客户端 JS；只有文件顶部写了 "use client" 才成为客户端组件，用来处理 useState、事件和浏览器 API。最佳实践是把客户端组件推到叶子节点，需要交互的地方才切边界。

Next.js App Router 项目里为什么会出现"水瀑式"串行请求，慢在哪里？

本可并行的请求被迫排队，后一个等前一个完成。App Router 里布局嵌套、RSC 逐层渲染、客户端组件等 RSC Payload 到达才发请求，三层串行叠加，所以更易出现。把数据获取提升到同一层用 Promise.all 并行、用同级 Suspense 流式输出，能消除瓶颈。

Next.js 15 里 params、cookies 这些为什么从同步变成了异步，旧写法会怎样？

这是向 React 19 异步数据模型对齐：同步读取会阻塞流式渲染管道，改成 Promise 后组件可 await，下游静态部分先流出。Next.js 15 仍兼容旧的同步写法但会报 deprecation 警告，到 16 直接报错；可用 @next/codemod 自动迁移。

Next.js 的 App Router 和 Pages Router 是什么关系，定位有什么不同？

Pages Router 是传统路由，组件默认客户端、靠 getServerSideProps 等取数，无原生嵌套布局与流式渲染。App Router 是 13.4+ 推荐方案，基于 RSC，服务端组件优先、原生支持嵌套布局、Suspense 流式和 Server Actions。新项目建议用 App Router，存量项目无需强制迁移。