Next.js最佳实践Skill：把 App Router 的架构决策变成可复用的团队约定
- 一句话定位：它不是代码生成器，而是一套「Next.js App Router 开发原则」的技能包，专门回答“这块代码该放服务器组件还是客户端组件”“数据在哪里取”“缓存怎么设”这类高频架构判断题。
- 核心能力：覆盖服务器/客户端组件决策树、数据获取模式、路由文件约定、API 路由、性能优化、元数据、缓存策略、服务器操作、反模式清单、项目结构共 10 个主题。
- 使用门槛低：技能声明可调用「读取、写入、编辑、全局、搜索」等工具，意味着它不只能“讲道理”，还能读取你的项目文件、搜索代码、给出针对当前仓库的改写建议。
- 最大差异点：内置「反模式对照表」，把“到处
'use client'”“在客户端组件里取数”这类常见坏味道直接列成 ❌/✅ 对照，评审和自检时非常好用。 - 适用人群：正在用或准备用 App Router 的前端开发者、技术负责人、从 Pages Router 迁移的团队，以及需要统一代码约定的多人协作项目。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
基本信息
| 项目 | 内容 |
|---|---|
| 中文名 | Next.js最佳实践Skill |
| 英文名 | nextjs-best-practices |
| 技能ID | 12172 |
| 技能描述 | Next.js App Router 原则：服务器组件、数据获取、路由模式 |
| 可调用工具 | 读取、写入、编辑、全局、搜索 |
它解决什么问题
Next.js 的 App Router 引入了一套新的心智模型：默认服务器组件、fetch 缓存语义、page.tsx/layout.tsx/loading.tsx/error.tsx 的文件约定、路由组与并行路由、服务器操作等等。这些东西单看文档都懂，但落到真实项目里，团队常见的问题是：
- 新人分不清什么时候该写
'use client'，干脆全加上，客户端包越来越大； - 数据获取一会儿在客户端
useEffect里做，一会儿在服务器组件里做，风格不统一； - 缓存策略靠“感觉”，
revalidate和no-store随手写； - 代码评审时各说各话，缺少一份可以共同引用的“团队公约”。
这个技能的价值，就是把这些原则固化成一份结构化、可被 AI 直接调用的规范：当你在对话里问出架构问题时，它给出的不是泛泛而谈，而是决策树 + 对照表 + 明确结论。
一键安装的思路与步骤
安装的具体命令与入口由你所使用的 AI 平台/客户端决定，请以官方说明为准。通用流程如下：
- 确认前提：你的 AI 编程助手需要支持「技能（Skill）」机制，并且允许技能调用读取/搜索等工具（本技能声明了读取、写入、编辑、全局、搜索）。若不支持工具调用，技能仍可做知识性回答，但无法读取你的项目文件。
- 找到安装入口：在平台的技能市场 / 技能管理页 / 技能列表中，通过搜索技能名
nextjs-best-practices、中文名「Next.js最佳实践」或技能ID12172定位该技能。 - 一键启用：点击安装或启用，按提示完成授权（尤其是文件读取与搜索权限）。具体授权项以官方说明为准。
- 验证是否生效：新建一个对话，直接问一句“我的 Next.js 项目里，一个带搜索框的列表页该怎么拆组件？”，如果回答中出现了服务器组件 / 客户端组件的决策树式判断，并且引用了
loading.tsx、error.tsx等文件约定，说明技能已正常加载。 - 进阶验证：让它在当前项目里搜索所有包含
'use client'的文件并给出精简建议，若能正常读取并列举文件，说明工具权限也已生效。
2. 该技能的主要功能和特点
- 服务器/客户端组件决策树：以“是否需要
useState、useEffect、事件处理程序”为起点，明确划分客户端组件、服务器组件，以及“两者都需要时拆分为服务器父组件 + 客户端子组件”的第三种解法。 - 默认情况约定表：服务器组件负责数据获取、布局、静态内容；客户端组件负责表单、按钮、交互式 UI。这条默认规则能有效抑制
'use client'的滥用。 - 数据获取模式分类：把获取策略拆成默认（构建时缓存的静态）、重新验证（基于时间刷新的 ISR）、
no-store（每次请求的动态）三类，并按数据来源（数据库 / API / 用户输入）给出对应的推荐模式。 - 路由文件约定速查：
page.tsx、layout.tsx、loading.tsx、error.tsx、not-found.tsx各自的职责一目了然，避免“只写页面、不写加载态和错误边界”的常见遗漏。 - 高级路由组织模式：路由组
(name)组织目录而不影响 URL、并行路由@slot实现同级多页面、拦截路由(.)实现模态叠加层。 - API 路由规范：按 GET/POST/PUT/PATCH/DELETE 划分用途，并强调用 Zod 校验输入、返回恰当状态码、优雅处理错误、尽量使用 Edge 运行时。
- 性能原则：图像侧强调
next/image、首屏图片设优先级、模糊占位符、响应式尺寸；包体积侧强调重量级组件动态导入、路由级自动代码拆分、用包分析器定位问题。 - 元数据规范：区分静态导出与
generateMetadata动态生成，并给出标题 50–60 字符、描述 150–160 字符、Open Graph 图、规范 URL 的具体标准。 - 三层缓存模型：请求层（
fetch选项）、数据层（revalidate/tags）、整路由层（路由配置），配合基于时间、按需（revalidatePath/revalidateTag）、无缓存三种重新验证方式。 - 服务器操作最佳实践：适用表单提交、数据突变、触发重新验证；要求用
'use server'标记、校验所有输入、返回类型化响应、处理错误。 - 反模式对照表：把“到处
'use client'”“在客户端组件中获取数据”“跳过加载状态”“忽略错误边界”“大客户端包”等逐条列出 ❌ 与 ✅，是评审时最实用的部分。 - 项目结构示例：给出
app/下路由组、布局、api/[resource]/route.ts、components/ui/的推荐组织方式。
和普通工具比强在哪？ 普通文档是“知识”，静态检查工具是“事后报警”，而这个技能是事前的架构顾问——它能在你写代码之前，用决策树帮你把结构定下来，并且能读你的项目，指出哪些文件正踩在反模式上。
3. 如何使用该技能？
步骤一：明确你问的是“决策类问题”还是“改造类问题”
- 决策类：选组件类型、选数据获取方式、选缓存策略、定目录结构；
- 改造类：请它读取现有文件，找出违规点并给出改法。 两类问题它都能接，但把问题问清楚，答案质量差别很大。
步骤二：用“场景 + 约束”的方式描述输入
不推荐：“Next.js 怎么写比较好？” 推荐：“我有一个商品列表页，需要支持关键词搜索和时间筛选，数据来自数据库，首屏要 SEO 友好，用户切换筛选条件时不能整页刷新。请告诉我组件怎么拆、数据在哪取、缓存怎么设。”
步骤三：读取技能给出的结构化结论
预期输出大致长这样：
- 页面外壳（
page.tsx）保持服务器组件，负责从数据库取初始数据，保证 SEO 与首屏； - 搜索框、筛选下拉、分页按钮拆成客户端子组件，通过 props 接收初始值；
- 筛选后的数据刷新走服务器操作或路由处理器，而不是客户端直连数据库；
- 缓存上，初始列表可用基于时间的重新验证（如
revalidate: 60），用户提交筛选后按需revalidatePath或revalidateTag； - 补充
loading.tsx处理加载态、error.tsx处理错误边界、not-found.tsx处理空结果。
步骤四：让它对齐你的实际项目
让技能使用搜索工具扫描项目，例如问：“搜索项目里所有 'use client' 文件，逐个判断是否可以改回服务器组件。”它会结合决策树给出逐个文件的结论。
步骤五：让它执行改造
技能声明了写入与编辑权限，可以让它直接修改文件。建议先让它输出改动清单，你确认后再写入，避免一次性大范围改动难以回滚。
步骤六：把结论沉淀成团队约定
让它把项目实际采用的规则整理成一份 README 或约定文档，这样下次评审就有共同基准。
输入示例（可直接参考）：
“我的表单提交后要刷新列表，但不要整页跳转。请按 Next.js App Router 的最佳实践给出实现路径，并说明输入校验和错误返回该怎么写。”
预期输出要点：表单放在客户端组件里（需要交互）、用服务器操作处理提交（'use server' 标记）、用 Zod 校验输入、返回类型化响应（成功/字段错误/系统错误三态）、成功后调用 revalidatePath 或 revalidateTag 刷新数据、错误用 error.tsx 兜底。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势 | 不足 |
|---|---|---|---|---|---|---|
| Next.js最佳实践Skill（nextjs-best-practices） | 嵌入 AI 助手的 App Router 架构顾问 | 组件决策树、数据获取模式、路由约定、缓存三层模型、反模式清单、项目结构 | 需在支持 Skill 的平台启用，授权读取/搜索/写入等工具，具体以官方说明为准 | 项目起步定架构、代码评审、迁移改造、新人带教 | 决策前置、能读项目文件、结论结构化成表格与决策树 | 依赖平台能力；AI 结论仍需人工复核；不替代真实运行验证 |
| Next.js 官方文档 | 权威知识源 | 全量 API、迁移指南、示例 | 免费、无需安装，浏览器可读 | 查具体 API、看官方推荐 | 最权威、覆盖最全、随版本更新 | 信息量大、需自己提炼；不针对你的项目给结论 |
| ESLint / Next.js 静态检查规则 | 代码级自动化检查 | 规则校验、CI 拦截 | 需配置依赖与规则集 | 提交前拦截、CI 卡口 | 可自动化、结果客观、可进流水线 | 只能发现“已写错”的问题，无法在动手前给架构建议 |
| 通用大模型直接问答（不使用技能） | 通用问答 | 依赖模型自身知识 | 零配置 | 简单问题速查 | 快、无门槛 | 缺少固定的原则框架，结论不稳定；对 App Router 细节容易含糊或过时 |
怎么选：如果你要的是“标准答案”，查官方文档；要的是“拦住错误”，配静态检查；要的是“在动手之前把结构定对、并把理由讲清楚”，用这个技能会明显更省时间。三者可以叠加使用，并不互斥。
5. 该技能的典型应用场景与实际体验情况
场景一：新人接手 App Router 项目，卡在组件类型判断
角色：刚从前端框架转入 Next.js 的开发者。
痛点：看到代码里一半文件有 'use client'、一半没有，不明白分界线在哪，于是习惯性全都加上。
使用方式：直接问“这个页面有侧边栏导航、一个表格、一个新增弹窗，哪些该是客户端组件？”技能会用决策树逐项拆解：导航与表格外壳留在服务器组件，弹窗和按钮因为要处理点击事件拆成客户端子组件。
实际体验：上手难度低，几乎不需要学习成本。效果是能一次性把“为什么这样拆”讲清楚，而不只是给代码。注意点是——它给的是原则，真正落地时要结合你们团队的目录约定微调。
场景二：技术负责人做代码评审
角色：负责 code review 的 Tech Lead。
痛点：评审意见散落在各处，缺少统一说法，容易变成个人偏好之争。
使用方式：让它读取待评审的目录，输出“反模式清单对照结果”：哪些文件可以去掉 'use client'、哪些地方缺 loading.tsx、哪些接口没有输入校验。
实际体验：这是最能体现价值的一类用法，因为反模式表把“❌ 不要 / ✅ 要做”写死了，评审意见有了可引用的依据。注意点是别让它直接改文件——先出清单、人工确认，再批量执行。
场景三：Pages Router 向 App Router 迁移
角色：维护一个老项目的开发者。
痛点：迁移不是改语法，而是改数据获取方式（从 getServerSideProps 迁到服务器组件）和路由组织。
使用方式：按模块提问，“这个列表模块迁移过来后，数据在哪取、缓存怎么设、加载态怎么加”，让它按“数据来源 → 获取模式 → 缓存策略”的顺序给方案。
实际体验：结构化的分类（默认静态 / 重新验证 / 无缓存）能避免“一刀切用动态渲染”导致的性能回退。注意点是版本差异——不同 Next.js 版本的缓存默认行为有变化，务必以你自己项目的版本与官方说明为准，并用真实构建验证。
场景四：性能与 SEO 优化专项
角色：负责站点性能的工程师。
痛点：图片体积大、客户端包膨胀、页面 title 与 description 全靠手写。
使用方式：让它按“性能原则 + 元数据规范”过一遍：图片是否用 next/image、首屏图是否设了优先级、重组件是否动态导入、标题是否控制在 50–60 字符、描述是否 150–160 字符、是否配了 Open Graph 图与规范 URL。
实际体验：可作为检查清单使用，覆盖度不错。注意点是它给的是“应该做什么”，具体收益仍需用 Lighthouse、包分析器等工具实测确认。
6. 该技能能为用户带来的价值
把架构判断从“凭感觉”变成“有依据”。App Router 最大的成本不是写代码，而是决策成本。有了决策树，团队里关于“要不要 'use client'”的争论可以几分钟内收敛。
统一团队约定，降低协作摩擦。反模式对照表天然就是一份评审标准，新人按它自查，评审者按它提意见，沟通成本显著下降。
减少返工。默认服务器组件、数据在服务器取、客户端只保留交互——这三条一旦落地，能避免后期“客户端包过大需要重构”“组件边界混乱需要重拆”这类高成本返工。
降低学习门槛。对刚接触 App Router 的开发者，这份技能相当于一位随时在线的架构导师，把官方文档里分散的章节压缩成决策树和表格。
可量化的观测思路（不编造具体数字，建议自行统计）：统计项目内 'use client' 文件数量占比的变化、客户端包体积变化、缺失 loading.tsx/error.tsx 的路由数量、代码评审中架构类意见的往返轮次。这些指标都能在接入技能前后做一次对比。
长期价值：把默认规则固化成文档和约定后，这套原则会沉淀为团队资产，而不是只留在某个人的经验里。
7. 常见问题 FAQ
Q1：怎么安装这个技能？需要付费吗？
A：在支持技能机制的 AI 平台中，通过技能市场或技能列表搜索 nextjs-best-practices、中文名「Next.js最佳实践」或技能ID 12172 即可找到并一键启用，随后按提示授权读取、搜索等工具权限。是否收费、是否有额度限制由你使用的平台决定，请以官方说明为准。
Q2：它会不会直接改我的代码，有风险吗？
A：技能声明了读取、写入、编辑、全局、搜索等工具能力，确实具备改文件的条件。建议的用法是：先让它输出「改动清单 + 理由」，你确认后再让它执行写入，并确保项目已纳入版本管理，随时可回滚。
Q3：它适合谁用？不适合谁？
A：适合正在使用或计划使用 App Router 的前端开发者、做架构与评审的技术负责人、需要统一代码规范的多人团队。如果你还在 Pages Router 且短期不迁移，或者只是想查某个具体 API 的参数，直接看官方文档效率更高。
Q4：它和静态检查工具、官方文档该怎么配合？
A：三者定位不同——技能负责“动手前定架构”，静态检查负责“提交前拦错误”，官方文档负责“查权威细节”。推荐组合使用：用技能定方案，用静态检查守底线，遇到版本差异和边缘行为回到官方文档确认。
Q5：照着它给的缓存建议做，线上数据会不准吗？
A：缓存是 Next.js 中最容易出问题的部分，且不同版本的默认行为存在差异。技能给出的是「请求层 / 数据层 / 整路由层」三层模型和基于时间、按需、无缓存三种手段，属于决策框架；具体取值必须结合你的业务容忍度，并在真实环境中验证，最终以你所用版本的官方说明为准。