第二章：项目搭建——Next.js 15 + TypeScript + Tailwind

第二章：项目搭建——Next.js 15 + TypeScript + Tailwind

“项目结构决定了后续开发的天花板。一个好的目录结构让 AI 工具更容易理解代码组织。”

2.1 初始化项目

npx create-next-app@latest my-saas-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

2.2 安装核心依赖

# UI 组件库
npx shadcn@latest init
npx shadcn@latest add button input label form dialog

# 数据获取与状态
npm install swr zustand

# 表单验证
npm install react-hook-form zod @hookform/resolvers

# 图标
npm install lucide-react

2.3 项目目录结构

src/
├── app/                          # Next.js App Router
│   ├── layout.tsx                # 根布局
│   ├── globals.css               # 全局样式
│   ├── (marketing)/              # 营销页面组
│   │   ├── page.tsx              # 首页
│   │   └── pricing/page.tsx      # 定价页
│   └── (app)/                    # 应用页面组
│       ├── layout.tsx            # 应用布局
│       └── dashboard/page.tsx    # Dashboard
├── components/
│   ├── ui/                       # shadcn/ui 组件
│   └── features/                 # 业务组件
│       ├── auth/
│       └── projects/
├── lib/
│   ├── api.ts                    # API 客户端
│   ├── auth.ts                   # 认证工具
│   └── utils.ts                  # 通用工具
├── hooks/
│   ├── use-auth.ts
│   └── use-projects.ts
├── store/
│   └── auth-store.ts
└── types/
    └── api.ts

2.4 环境变量配置

# .env.local（本地开发）
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxx

# 服务端变量（不带 NEXT_PUBLIC_，不暴露给浏览器）
AUTH_SECRET=your-secret-key

原则：NEXT_PUBLIC_ 前缀的变量会被打包进浏览器 JS，敏感信息不能用此前缀。

2.5 API 客户端封装

所有 API 调用通过统一封装：

sequenceDiagram
    浏览器->>Next.js API Route: /api/xxx
    Next.js API Route->>FastAPI: 转发请求
    FastAPI->>Next.js API Route: JSON 响应
    Next.js API Route->>浏览器: JSON
    Note over Next.js API Route: 自动携带 httpOnly Cookie

封装要点：

  1. 统一错误处理
  2. 自动携带认证 Cookie
  3. 类型安全

本章小结

  1. 初始化：create-next-app + shadcn/ui
  2. 目录结构：feature-based 组织
  3. 环境变量：NEXT_PUBLIC_ 原则
  4. API 封装：统一错误处理 + 类型安全

本章提示词模板

生成 API 客户端

为以下后端 API 生成 TypeScript API 客户端：

后端端点：
- POST /auth/login → { access_token: string }
- POST /auth/register → { access_token: string }
- GET /projects/ → PaginatedResponse<Project>
- POST /projects/ → Project

请生成：
1. TypeScript 类型定义（对应 Pydantic models）
2. 统一的 request 函数（处理错误、Header）
3. api 对象（按模块组织）
4. APIError 类

API 基础 URL：process.env.NEXT_PUBLIC_API_URL
认证方式：Bearer Token 在 Authorization Header

分析目录结构

分析以下项目需求，设计目录结构：

项目类型：SaaS 应用
功能模块：用户认证、项目管理、资产管理、订阅支付

请输出：
1. app/ 目录结构（路由组设计）
2. components/ 目录结构
3. lib/ 需要哪些模块
4. hooks/ 需要哪些自定义 hooks
5. types/ 需要哪些类型定义

技术栈：Next.js 15 App Router, TypeScript

继续阅读：第三章：AI生成UI