Git 规范

核心原则

Git 提交必须遵循 Conventional Commits 规范，使用中文编写提交信息。

允许的做法

提交信息格式

遵循 Conventional Commits 格式：

<类型>[可选范围]: <描述>

[可选正文]

[可选脚注]

# ✅ 正确 - 基本格式
git commit -m "feat: 添加用户登录功能"
git commit -m "fix: 修复订单计算错误"

# ✅ 正确 - 包含范围
git commit -m "feat(auth): 添加 JWT 认证"
git commit -m "fix(order): 修复价格计算精度问题"

# ✅ 正确 - 包含正文
git commit -m "feat: 添加用户搜索功能

- 支持按用户名搜索
- 支持按邮箱搜索
- 添加分页功能"

提交类型（type）

类型	说明	示例
feat	新功能	feat: 添加用户注册功能
fix	Bug 修复	fix: 修复登录验证错误
docs	文档更新	docs: 更新 API 文档
style	代码格式调整（不影响逻辑）	style: 格式化代码
refactor	代码重构	refactor: 优化数据库查询
perf	性能优化	perf: 优化列表渲染性能
test	测试相关	test: 添加用户服务单元测试
chore	构建/工具/依赖	chore: 更新依赖版本

范围（scope）

• 使用 小写字母
• 使用 模块名或功能域

# ✅ 正确
feat(user): 添加用户头像上传
fix(api): 修复响应格式错误
refactor(database): 优化查询性能

Breaking Changes（破坏性变更）

• 使用 ! 标记破坏性变更
• 使用 BREAKING CHANGE: 在正文说明

# ✅ 正确
git commit -m "feat!: 修改 API 响应格式

BREAKING CHANGE: API 响应格式从 { data } 改为 { success, data }"

# ✅ 正确
git commit -m "refactor(api)!: 重构用户认证接口"

分支命名

• 使用 kebab-case（短横线）命名分支
• 使用 类型前缀

# ✅ 正确
feature/user-authentication
bugfix/login-validation
hotfix/critical-security-patch
refactor/optimize-queries

提交频率

• 遵循 原子性提交原则
• 确保 每次提交代码可运行
• 一个提交 只做一件事

# ✅ 正确 - 原子性提交
git commit -m "feat(user): 添加用户表单组件"
git commit -m "feat(user): 添加用户服务 API 调用"
git commit -m "test(user): 添加用户服务单元测试"

禁止的做法

禁止的提交信息

• 禁止 不符合 Conventional Commits 格式
• 禁止 添加 emoji 符号
• 禁止 添加工具生成信息（如 "🤖 Generated with Claude Code"）
• 禁止 添加 Co-Authored-By 签名
• 禁止 模糊的描述

# ❌ 错误
git commit -m "update"                    # 缺少类型
git commit -m "fixed bug"                 # 缺少类型和具体说明
git commit -m "feat: 添加功能 🎉"          # 包含 emoji
git commit -m "更新代码"                   # 缺少类型
git commit -m "feat:添加功能"             # 冒号后缺少空格

禁止的操作

• 禁止 提交大文件（> 10MB）
• 禁止 提交敏感信息（密钥、密码）
• 禁止 提交自动生成的文件
• 禁止 直接推送到 main/master 分支
• 禁止 强制推送到共享分支

# ❌ 错误
git add .env                      # 敏感文件
git add node_modules/             # 自动生成
git push --force origin main      # 强制推送

工作流程

Feature 开发流程

# 1. 创建功能分支
git checkout -b feature/user-profile

# 2. 开发并提交
git add src/components/UserProfile.tsx
git commit -m "feat(user): 添加用户资料组件"

git add src/services/user.ts
git commit -m "feat(user): 添加用户资料 API"

# 3. 推送到远程
git push -u origin feature/user-profile

Hotfix 紧急修复流程

# 1. 从 main 创建 hotfix 分支
git checkout main
git pull
git checkout -b hotfix/payment-bug

# 2. 修复并提交
git add src/services/payment.ts
git commit -m "fix(payment): 修复金额计算错误"

# 3. 合并回 main
git checkout main
git merge hotfix/payment-bug
git push origin main

提交信息示例

新功能

feat: 添加用户登录功能
feat(auth): 添加 JWT 认证支持
feat(api): 添加用户搜索接口

Bug 修复

fix: 修复登录验证错误
fix(order): 修复订单金额计算精度
fix(ui): 修复移动端布局错乱

重构

refactor: 优化数据库查询逻辑
refactor(user): 简化用户服务代码
refactor(api): 统一错误处理机制

文档

docs: 更新 README 文档
docs(api): 添加 API 使用说明
docs: 补充部署文档

性能优化

perf: 优化列表渲染性能
perf(database): 添加查询索引
perf(image): 启用图片懒加载

测试

test: 添加用户服务单元测试
test(auth): 添加登录集成测试
test: 提高测试覆盖率到 80%

构建和工具

chore: 更新依赖版本
chore: 配置 ESLint 规则
chore(ci): 添加 GitHub Actions 工作流

特殊规则

.gitignore 配置

# 环境配置
.env
.env.local
config.toml

# 构建产物
dist/
build/
.vitepress/dist/

# 依赖
node_modules/
vendor/

# IDE
.vscode/
.idea/
*.swp

# 日志
*.log
logs/

合并策略

• 使用 Squash Merge 合并 Feature 分支
• 使用 Merge Commit 合并 Release 分支
• 保留 Conventional Commits 格式的提交历史

相关文档

• 代码风格 - 代码格式化规范
• Conventional Commits 规范