fec-nextjs-project-standard

Next.js 项目规范

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

用途

规范 Next.js 14+ 项目中 App Router、SSR/SSG/ISR 渲染模式、数据获取、路由布局、中间件和 SEO 元数据的工程实践，确保服务端优先、性能优化和可维护性。

流程

1. 先识别目标属于 App Router、布局、服务端数据、middleware、metadata 还是客户端交互。
2. 默认服务端组件优先；只有需要浏览器 API、交互状态或事件处理时才使用 'use client'。
3. 明确 SSR / SSG / ISR / CSR 渲染模式和 Next fetch/cache 策略。
4. 为路由补齐 loading.tsx、error.tsx、not-found.tsx、metadata 和敏感逻辑的服务端边界。
5. 引入第三方库前检查是否支持 Server Component；浏览器专属、动效、图表、编辑器和 WebGL 库必须放进客户端叶子组件并按需加载。
6. 对动态渲染、缓存失效、RSC 序列化、route handler、middleware 和首屏 bundle 做证据优先审查；不确定时先收集构建、trace、headers 或路由行为证据。
7. 客户端组件架构问题分流到 React 项目 workflow。

项目结构

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

数据获取

• 服务端组件：直接 async 或 fetch，不暴露 useEffect
• 客户端组件：useEffect + useState，或 SWR / React Query
• 优先在服务端获取数据，减少客户端水合
• 使用 loading.tsx 和 Suspense 包裹异步区块，提供流式体验
• 缓存策略要写清 force-cache、no-store、revalidate、tag/path revalidation 或用户私有数据约束
• 任何会让路由从静态变动态的读取（cookies、headers、searchParams、未缓存 fetch）都要说明原因和验证方式