freedakgmail
167 lines
2.7 KiB
Markdown
167 lines
2.7 KiB
Markdown
# 本地开发指南
|
|
|
|
## 快速启动
|
|
|
|
### 1. 安装依赖
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
### 2. 配置环境变量
|
|
|
|
复制 `.env.example` 到 `.env` 并配置：
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
编辑 `.env` 文件，配置数据库连接：
|
|
|
|
```env
|
|
DATABASE_URL="postgresql://user:password@localhost:5432/chinese_family_tree"
|
|
NEXTAUTH_URL="http://localhost:3000"
|
|
NEXTAUTH_SECRET="your-secret-key"
|
|
```
|
|
|
|
### 3. 初始化数据库
|
|
|
|
```bash
|
|
# 生成 Prisma Client
|
|
npx prisma generate
|
|
|
|
# 同步数据库结构
|
|
npx prisma db push
|
|
```
|
|
|
|
### 4. 启动开发服务器
|
|
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
|
|
访问 http://localhost:3000
|
|
|
|
## 常见问题
|
|
|
|
### Prisma Client 错误
|
|
|
|
**错误信息**:
|
|
```
|
|
Error: Failed to load external module @prisma/client
|
|
```
|
|
|
|
**解决方案**:
|
|
```bash
|
|
# 重新生成 Prisma Client
|
|
npx prisma generate
|
|
|
|
# 同步数据库
|
|
npx prisma db push
|
|
```
|
|
|
|
### 数据库连接错误
|
|
|
|
**确保 PostgreSQL 已启动**:
|
|
```bash
|
|
# macOS
|
|
brew services start postgresql
|
|
|
|
# 或检查状态
|
|
brew services list
|
|
```
|
|
|
|
**创建数据库**:
|
|
```bash
|
|
# 连接到 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
|
|
|
|
可视化数据库管理工具：
|
|
|
|
```bash
|
|
npx prisma studio
|
|
```
|
|
|
|
访问 http://localhost:5555
|
|
|
|
### 数据库迁移
|
|
|
|
```bash
|
|
# 创建迁移
|
|
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 格式化代码
|
|
|
|
## 提交代码
|
|
|
|
```bash
|
|
# 格式化代码
|
|
pnpm format
|
|
|
|
# 检查类型
|
|
pnpm type-check
|
|
|
|
# 提交
|
|
git add .
|
|
git commit -m "feat: your message"
|
|
```
|