NextJS

核心用法

本 Skill 提供 Next.js App Router 架构下的系统性避坑指南，覆盖服务端组件（Server Components）与客户端组件（Client Components）的边界划分、数据获取模式、缓存策略、Server Actions、Middleware 及路由处理等关键领域。

服务端/客户端边界：App Router 默认使用服务端组件，禁止直接使用 useState、useEffect 及浏览器 API；需通过 'use client' 指令标记客户端组件，且服务端组件不可被客户端组件直接导入，仅能通过 children 或 props 传递。

数据获取与性能：推荐在服务端组件中直接 fetch，避免 useEffect 瀑布请求；使用 Promise.all 实现并行获取；loading.tsx 与 error.tsx 自动提供 Suspense 边界与错误捕获。

缓存策略：服务端组件中的 fetch 默认缓存，需显式设置 cache: 'no-store' 获取动态数据；ISR 通过 next: { revalidate: 60 } 配置；按需刷新使用 revalidatePath 或 revalidateTag。

Server Actions：'use server' 标记的函数可在客户端组件中直接调用，支持表单渐进增强（无 JavaScript 亦可工作），数据变更后需主动触发缓存刷新。

显著优点

• 官方权威性：内容直接源自 Vercel/Next.js 核心团队工程实践，反映最新 App Router 架构设计
• 场景覆盖全：从组件边界、数据获取、缓存、路由处理到边缘中间件，涵盖全栈开发关键决策点
• 错误导向设计：以"常见错误"为切入点，针对性强，适合快速定位生产环境实际问题
• 性能优化导向：明确区分 SSR、SSG、ISR、动态渲染的适用场景，避免过度或不足优化

潜在局限

• 快速迭代风险：Next.js App Router 处于高速迭代期，部分行为（如默认缓存策略）在 v14-v15 间已有调整，内容可能随版本过时
• 边缘情况覆盖有限：复杂状态管理（如 React Server Actions 与外部状态库结合）、大型应用代码分割策略未深入展开
• 生态兼容性：部分第三方库（如某些 Node.js 原生模块）在 Edge Runtime 与 Server Components 中的兼容性问题未详细列举

适合人群

• 从 Pages Router 迁移至 App Router 的中高级 React 开发者
• 需要处理服务端渲染、边缘计算、ISR 缓存策略的全栈工程师
• 追求 Core Web Vitals 优化与 SEO 友好的前端架构师

常规风险

• 缓存失效陷阱：默认缓存行为理解偏差可能导致生产环境数据陈旧，建议在关键动态路由显式声明 dynamic = 'force-dynamic'
• 环境变量泄露：误将敏感配置添加 NEXT_PUBLIC_ 前缀会导致客户端暴露
• Server Actions 滥用：过度使用可能绕过类型安全与权限控制，建议在 actions 中显式校验用户身份

核心用法

该 Skill 是一份系统性的 Next.js 开发防错手册，聚焦于 App Router 架构下的关键认知盲区。核心使用方式是将文档作为开发参考，在以下场景快速检索解决方案：

• 组件边界判定：默认 Server Component，需显式标记 'use client' 才能使用 React hooks 和浏览器 API
• 数据获取策略：Server Component 内直接 fetch，配合 loading.tsx 实现流式加载，避免客户端 useEffect 瀑布请求
• 缓存精细控制：fetch 默认缓存，通过 cache: 'no-store' 或 next.revalidate 实现 ISR；revalidatePath/revalidateTag 支持按需刷新
• Server Actions：'use server' 标记的函数可被 Client Component 直接调用，自动完成 RPC 通信，表单支持渐进增强

显著优点

1. 认知框架清晰：将容易混淆的概念（如 Server/Client 边界、动态/静态路由）用简洁条目拆解，降低心智负担
2. 实战导向：每个条目对应具体代码场景（如 cookies() 导致路由动态化、router.push 在 Server Component 中无效），避免纸上谈兵
3. 性能意识贯穿：强调并行 fetch、Suspense 边界、缓存策略，契合 Next.js 性能优化核心诉求

潜在局限

• 版本时效性：Next.js 迭代迅速（如 Server Actions 从实验到稳定），部分细节可能随版本变化
• 深度不足：作为速查手册，对复杂场景（如 Edge Runtime 的完整限制、大型应用的缓存架构设计）缺乏展开
• 无代码验证：纯文档形态，无法直接检测用户项目是否真实规避了所列问题

适合人群

• 从 Pages Router 迁移至 App Router 的开发者
• 团队内需要统一 Next.js 最佳实践规范的 Tech Lead
• 对 React Server Components 概念模糊、频繁踩坑的前端工程师

常规风险

• 过度缓存导致数据陈旧：fetch 默认缓存机制若未理解透彻，可能引发生产环境数据不同步
• Server Action 滥用：将过重逻辑放入 Server Action 可能影响响应时间，且调试复杂度高于传统 API 路由
• Edge Runtime 限制踩坑：Middleware 中无法使用 Node.js 原生模块，错误假设可能导致运行时崩溃

> 该 Skill 为纯文档型指南，无可执行代码，无网络调用，无敏感数据收集，安全等级为 S+，可放心作为技术参考使用。