chinese-family-tree-2/LOCAL_DEV_GUIDE.md

本地开发指南

快速启动

1. 安装依赖

pnpm install

2. 配置环境变量

复制 .env.example 到 .env 并配置：

cp .env.example .env

编辑 .env 文件，配置数据库连接：

DATABASE_URL="postgresql://user:password@localhost:5432/chinese_family_tree"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-key"

3. 初始化数据库

# 生成 Prisma Client
npx prisma generate

# 同步数据库结构
npx prisma db push

4. 启动开发服务器

pnpm dev

访问 http://localhost:3000

常见问题

Prisma Client 错误

错误信息:

Error: Failed to load external module @prisma/client

解决方案:

# 重新生成 Prisma Client
npx prisma generate

# 同步数据库
npx prisma db push

数据库连接错误

确保 PostgreSQL 已启动:

# macOS
brew services start postgresql

# 或检查状态
brew services list

创建数据库:

# 连接到 PostgreSQL
psql postgres

# 创建数据库
CREATE DATABASE chinese_family_tree;

# 退出
\q

多 lockfile 警告

警告信息:

Warning: Next.js inferred your workspace root, but it may not be correct.

说明: 这是因为在父目录检测到其他 lockfile，已在 next.config.mjs 中配置 turbo.root 来消除此警告。

Session 错误

错误信息:

[next-auth][error][CLIENT_FETCH_ERROR]

解决方案:

1. 确保数据库已初始化：npx prisma db push
2. 确保 .env 中的 NEXTAUTH_URL 正确
3. 重启开发服务器

开发工具

Prisma Studio

可视化数据库管理工具：

npx prisma studio

访问 http://localhost:5555

数据库迁移

# 创建迁移
npx prisma migrate dev --name migration_name

# 应用迁移
npx prisma migrate deploy

查看日志

开发服务器会自动显示日志。如需查看详细日志，可以在代码中添加 console.log()。

项目结构

├── app/                    # Next.js App Router
│   ├── api/               # API 路由
│   ├── auth/              # 认证页面
│   └── ...
├── components/            # React 组件
├── lib/                   # 工具函数
├── prisma/               # 数据库 Schema
│   └── schema.prisma
├── .env                  # 环境变量（不提交到 Git）
└── next.config.mjs       # Next.js 配置

代码规范

• 使用 TypeScript
• 遵循 ESLint 规则
• 使用 Prettier 格式化代码

提交代码

# 格式化代码
pnpm format

# 检查类型
pnpm type-check

# 提交
git add .
git commit -m "feat: your message"