开发工作流

分支策略

main - 生产环境分支，受保护
develop - 开发分支
feature/* - 功能分支
fix/* - 修复分支

提交流程


# 1. 创建功能分支
git checkout -b feature/new-feature
 
# 2. 开发并提交
git add .
git commit -m "feat: add new feature"
 
# 3. 提交前检查
pnpm fix    # 自动修复代码格式问题
pnpm check  # 检查代码质量
 
# 4. 推送并创建 PR
git push origin feature/new-feature

代码质量

使用 Ultracite （基于 Biome）进行代码质量管理：


# 自动修复
pnpm fix
 
# 检查（不修改）
pnpm check
 
# 诊断设置
pnpm dlx ultracite doctor

Commit 规范

遵循 Conventional Commits ：

feat: - 新功能
fix: - 修复 bug
docs: - 文档更新
style: - 代码格式（不影响功能）
refactor: - 重构
test: - 测试相关
chore: - 构建/工具链

常见问题

环境变量未定义错误

错误: Invalid environment variables: { DATABASE_URL: ['Required'] }

解决方案:

确保对应应用目录下的 .env 文件存在（packages/db/.env、apps/admin/.env 或 apps/api/.env）
检查变量名拼写是否正确
Admin 应用：检查 env.ts 中的配置
重启开发服务器


# 复制环境变量模板
cp packages/db/.env.example packages/db/.env
cp apps/admin/.env.example apps/admin/.env
cp apps/api/.env.example apps/api/.env  # 如果存在

Prisma Client 生成失败

错误: Prisma schema not found

解决方案:


cd packages/db
pnpm db:generate

端口已被占用

错误: Port 3000 is already in use

解决方案:


# macOS/Linux
lsof -ti:3000 | xargs kill -9
 
# 或者修改 .env 中的 PORT 变量

pnpm 安装依赖失败

解决方案:


# 清理缓存
pnpm store prune
 
# 删除 node_modules 和 lockfile
pnpm clean:all
 
# 重新安装
pnpm install