Next.js 项目规范

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

适用场景

• - 新建或修改 App Router 页面
• 配置 SSR / SSG / ISR
• 使用流式渲染、Suspense
• 数据获取、缓存、中间件
• 元数据与 SEO

项目结构

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/

渲染模式

数据获取

• - 服务端组件：直接 async 或 fetch，不暴露 useEffect
• 客户端组件：useEffect + useState，或 SWR / React Query
• 优先在服务端获取数据，减少客户端水合
• 使用 loading.tsx 和 Suspense 包裹异步区块，提供流式体验

路由与布局

• - 路由组 (auth) 不改变 URL，只影响布局
• 动态路由 [id] 配合 generateStaticParams 做 SSG
• layout.tsx 包裹子路由，共享 UI 与布局
• page.tsx 为叶子路由，不可嵌套

中间件

• - 放在 middleware.ts 根目录
• 用于鉴权、重定向、rewrite、Header 修改
• 尽量短小，避免阻塞请求

元数据与 SEO

• - 使用 metadata 或 generateMetadata 导出
• 支持 title、description、openGraph、twitter 等
• 动态路由用 generateMetadata(params) 生成

强约束

• - 服务端组件默认，仅在需要客户端交互时加 use client
• 不在服务端组件中直接使用 useState、useEffect、浏览器 API
• 敏感逻辑（如鉴权）放在服务端或 API Route，不暴露在客户端
• 图片使用 next/image，字体使用 next/font