Next.js 项目规范

---

name: nextjs-project-standard

description: Next.js 14+ 项目规范，涵盖 App Router、SSR/SSG、流式渲染、路由与布局、数据获取、中间件、元数据与 SEO。当用户在 Next.js 项目中创建、修改页面或模块时自动激活。

version: 1.0.0

---

# Next.js 项目规范

适用于使用 Next.js 14+ 与 App Router 的仓库。

适用场景

项目结构

src/
├── app/                        # App Router
│   ├── layout.tsx              # 根布局
│   ├── page.tsx                # 首页
│   ├── loading.tsx              # 全局 loading UI
│   ├── error.tsx                # 全局错误边界
│   ├── not-found.tsx           # 404
│   ├── globals.css
│   │
│   ├── (auth)/                 # 路由组
│   │   ├── login/
│   │   │   └── page.tsx
│   │   └── register/
│   │       └── page.tsx
│   │
│   ├── (dashboard)/            # 仪表盘路由组
│   │   ├── layout.tsx          # 共享布局
│   │   ├── dashboard/
│   │   │   └── page.tsx
│   │   └── users/
│   │       ├── page.tsx
│   │       └── [id]/
│   │           └── page.tsx
│   │
│   └── api/                    # API Routes
│       └── users/
│           └── route.ts
│
├── components/                 # 共享组件
├── lib/                        # 工具、配置
├── hooks/
├── services/
└── types/

渲染模式

| 模式 | 使用场景 | 实现方式 |

|------|----------|----------|

| **SSR** | 动态、需实时数据 | 默认，`fetch` 不缓存或 `cache: 'no-store'` |

| **SSG** | 静态内容 | `generateStaticParams` + 静态 `fetch` |

| **ISR** | 定期更新 | `revalidate` 或 `revalidatePath` |

| **CSR** | 客户端交互 | `'use client'` + `useEffect` 或 SWR/React Query |

数据获取

路由与布局

中间件

元数据与 SEO

强约束