核心用法
本 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 中显式校验用户身份