团队 Git 使用规范

Mon, 18 May 2026 08:29:14 +0000

本文档定义了团队使用 Git 的标准流程和规范，所有团队成员必须遵循。

版本：v1.0.0
最后更新：2026年
适用范围：所有项目

目录
分支管理规范
提交信息规范
工作流程规范
代码审查规范
命名规范
安全规范
工具与配置
常见场景处理
1. 分支管理规范
1.1 分支类型
主分支（Main Branches）
main / master

用途：生产环境代码
保护：✅ 必须通过 Pull Request 合并
禁止：❌ 禁止直接推送，禁止强制推送
develop

用途：开发环境代码，日常开发集成
保护：✅ 必须通过 Pull Request 合并
禁止：❌ 禁止直接推送
辅助分支（Supporting Branches）
feature/* - 功能开发分支

命名：feature/功能名称，如 feature/user-login
来源：从 develop 创建
目标：合并回 develop
生命周期：功能完成后删除
fix/* - Bug 修复分支

命名：fix/问题描述，如 fix/login-button-bug
来源：从 develop 创建
目标：合并回 develop
生命周期：修复完成后删除
hotfix/* - 紧急修复分支

命名：hotfix/紧急修复描述，如 hotfix/security-patch
来源：从 main 创建
目标：合并回 main 和 develop
生命周期：修复完成后删除
release/* - 发布准备分支

命名：release/版本号，如 release/1.0.0
来源：从 develop 创建
目标：合并回 main 和 develop
生命周期：发布完成后删除
1.2 分支命名规则
✅ 允许的命名：

使用小写字母
使用连字符 - 分隔单词
简洁但描述性
示例：feature/user-authentication、fix/payment-error
❌ 禁止的命名：

使用大写字母
使用下划线或空格
使用个人名称
使用特殊字符
示例：Feature/Login、fix_bug、zhangsan-feature
1.3 分支保护规则
main 分支保护
✅ 必须通过 Pull Request 合并
✅ 至少 1 位团队成员审查通过
✅ 必须通过所有 CI/CD 检查
✅ 禁止直接推送
✅ 禁止强制推送
✅ 禁止删除分支
develop 分支保护
✅ 必须通过 Pull Request 合并
✅ 至少 1 位团队成员审查通过
✅ 必须通过所有 CI/CD 检查
✅ 禁止直接推送
✅ 禁止强制推送
2. 提交信息规范
2.1 提交信息格式
<类型>(<范围>): <简短描述>

<详细描述（可选）>

<相关 Issue（可选）>

2.2 类型（Type）
类型  说明  示例
feat  新功能  feat(用户): 添加用户登录功能
fix  修复 Bug  fix(登录): 修复登录按钮点击无效的问题
docs  文档更新  docs: 更新 API 文档
style  代码格式调整  style: 修复代码缩进问题
refactor  代码重构  refactor(服务): 重构用户服务层
perf  性能优化  perf(数据库): 优化查询性能
test  测试相关  test: 添加登录功能单元测试
chore  构建/工具相关  chore: 更新依赖包版本
ci  CI/CD 配置  ci: 添加自动化测试流程
2.3 范围（Scope）
范围是可选的，用于标识提交影响的部分：

模块名：feat(用户): ...
文件名：fix(api.js): ...
组件名：feat(登录): ...
2.4 提交信息示例
✅ 好的提交信息：

feat(用户): 添加用户注册功能

实现了用户注册的完整流程：
- 添加注册表单验证
- 实现邮箱验证功能
- 添加密码加密存储

Closes #123
fix(支付): 修复支付接口超时问题

修复了支付接口在高峰期超时的问题，增加重试机制。

Fixes #456
❌ 不好的提交信息：

更新代码
修复bug
提交
WIP

2.5 提交频率
✅ 推荐：小步提交，完成一个小功能就提交
✅ 推荐：每个提交解决一个问题
❌ 禁止：大量不相关的更改放在一个提交中
❌ 禁止：提交无法编译或测试失败的代码
3. 工作流程规范
3.1 日常开发流程
开始新功能
# 1. 确保 develop 分支是最新的
git checkout develop
git pull origin develop

# 2. 创建功能分支
git checkout -b feature/user-login

# 3. 开始开发
# ... 编写代码 ...
开发过程
# 1. 查看修改状态
git status

# 2. 添加修改到暂存区
git add .

# 3. 提交更改
git commit -m "feat(用户): 实现登录功能"

# 4. 定期推送到远程
git push origin feature/user-login
完成功能
# 1. 确保代码通过测试
npm test

# 2. 确保代码符合规范
npm run lint

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

# 4. 在平台创建 Pull Request

3.2 Pull Request 流程
创建 Pull Request
填写信息：

清晰的标题
详细的描述
关联相关 Issue
添加截图（如适用）
检查清单：

代码已通过测试
已更新相关文档
已遵循代码规范
无控制台错误
已关联相关 Issue
请求审查：

指定至少 1 位审查者
添加相关标签
Pull Request 模板
## ???? 变更描述
简要描述本次 PR 的变更内容

## ???? 变更类型
- [ ] 新功能 (feat)
- [ ] Bug 修复 (fix)
- [ ] 文档更新 (docs)
- [ ] 代码重构 (refactor)
- [ ] 性能优化 (perf)
- [ ] 测试相关 (test)
- [ ] 其他 (chore)

## ???? 测试说明
描述如何测试这些变更

## ???? 截图（如适用）
添加相关截图或演示

## ✅ 检查清单
- [ ] 代码已通过测试
- [ ] 已更新相关文档
- [ ] 已遵循代码规范
- [ ] 无控制台错误
- [ ] 已关联相关 Issue

## ???? 相关 Issue
Closes #123

3.3 代码审查流程
审查者职责
及时响应：24 小时内响应审查请求

仔细审查：

代码功能正确性
代码质量和风格
性能和安全问题
测试覆盖
提供反馈：

建设性的意见
具体的改进建议
必要时提供代码示例
提交者职责
及时回复：及时回复审查意见
积极修改：根据反馈修改代码
保持沟通：对审查意见有疑问及时沟通
3.4 合并后清理
# 1. 切换到主分支
git checkout develop
git pull origin develop

# 2. 删除本地分支
git branch -d feature/user-login

# 3. 删除远程分支（如果 PR 合并时未自动删除）
git push origin --delete feature/user-login

4. 代码审查规范
4.1 审查检查清单
功能正确性：代码实现了预期功能
代码质量：代码清晰、可读、可维护
代码风格：遵循团队代码规范
性能：没有明显的性能问题
安全性：没有安全漏洞
错误处理：错误处理完善
测试：有足够的测试覆盖
文档：必要文档已更新
4.2 审查意见格式
✅ 好的审查意见：

这里可以优化一下，使用更简洁的方式：

```javascript
// 当前代码
const result = array.filter(item => item > 0).map(item => item * 2);

// 建议
const result = array.reduce((acc, item) => {
  if (item > 0) acc.push(item * 2);
  return acc;
}, []);

❌ 不好的审查意见：

这个不对
不好
需要改

4.3 审查状态
✅ 批准（Approve）：代码可以合并
⚠️ 需要修改（Request Changes）：需要修改后才能合并
???? 评论（Comment）：有疑问或建议，但不阻止合并
5. 命名规范
5.1 分支命名
见分支管理规范

5.2 提交信息命名
见提交信息规范

5.3 文件命名
使用小写字母
使用连字符或下划线分隔
避免使用空格和特殊字符
示例：user-service.js、user_model.py
6. 安全规范
6.1 敏感信息管理
❌ 禁止提交：

密码、密钥、Token
API 密钥
数据库连接字符串
个人隐私信息
配置文件中的敏感信息
✅ 正确做法：

使用环境变量
使用 .gitignore 排除敏感文件
使用密钥管理服务
提供 .env.example 模板
6.2 .gitignore 配置
# 环境变量
.env
.env.local
.env.*.local

# 密钥和证书
*.key
*.pem
*.cert
secrets/
*.secret

# 配置文件
config/production.json
config/local.json

# 日志文件
*.log
logs/

# 临时文件
*.tmp
*.temp
*.cache

6.3 访问控制
使用 SSH Keys 而非密码
定期轮换访问密钥
遵循最小权限原则
离职员工及时撤销权限
7. 工具与配置
7.1 必需工具
Git：版本 >= 2.30.0
代码托管平台：GitHub / GitLab / Gitee
代码审查工具：平台内置或第三方工具
7.2 推荐工具
Git GUI：SourceTree、GitKraken、GitHub Desktop
IDE 集成：VS Code、WebStorm、IntelliJ IDEA
提交信息检查：commitlint、husky
7.3 Git 配置
# 设置用户信息
git config --global user.name "你的姓名"
git config --global user.email "your.email@example.com"

# 设置默认编辑器
git config --global core.editor "code --wait"

# 设置默认分支名
git config --global init.defaultBranch main

# 启用颜色输出
git config --global color.ui true

# 设置推送行为
git config --global push.default simple

8. 常见场景处理
8.1 处理合并冲突
拉取最新代码：git pull origin develop
查看冲突文件：git status
手动解决冲突
标记已解决：git add
完成合并：git commit
8.2 紧急修复（Hotfix）
# 1. 从 main 创建 hotfix 分支
git checkout main
git pull origin main
git checkout -b hotfix/critical-bug

# 2. 修复问题并提交
git add .
git commit -m "fix: 修复紧急问题"
git push origin hotfix/critical-bug

# 3. 创建 Pull Request 合并到 main

# 4. 合并后同步到 develop
git checkout develop
git merge main
git push origin develop

8.3 撤销误提交
# 撤销未推送的提交
git reset --soft HEAD~1  # 保留更改在暂存区
git reset HEAD~1         # 保留更改在工作区
git reset --hard HEAD~1  # 丢弃所有更改（危险！）

# 撤销已推送的提交（推荐使用 revert）
git revert HEAD
git push origin branch-name

8.4 保存临时更改
# 保存当前更改
git stash

# 查看保存的更改
git stash list

# 恢复更改
git stash pop

9. 违规处理
9.1 违规行为
❌ 直接推送到保护分支
❌ 强制推送到共享分支
❌ 提交无法编译的代码
❌ 提交敏感信息
❌ 使用不规范的分支命名
❌ 提交信息不规范
9.2 处理措施
第一次：提醒并指导正确做法
多次违规：团队内讨论，必要时限制权限
严重违规：影响项目安全或稳定性时，立即处理
10. 更新与维护
10.1 规范更新
规范的更新需要团队讨论通过
更新后及时通知所有成员
更新版本号和日期
10.2 培训
新成员入职时进行 Git 规范培训
定期组织 Git 使用技巧分享
提供详细的文档和示例
附录
A. 快速参考
# 开始新功能
git checkout develop && git pull && git checkout -b feature/name

# 提交更改
git add . && git commit -m "feat: 描述" && git push

# 同步主分支
git checkout develop && git pull origin develop

# 查看状态
git status && git log --oneline -5

B. 相关文档
Git 基础入门
团队协作基础
团队协作注意事项
进阶技巧与最佳实践
推荐团队实践
C. 联系方式
如有问题或建议，请联系：

团队负责人：xxx
技术负责人：xxx
文档维护：xxx

[评论] 团队 Git 使用规范

Thu, 01 Jan 1970 00:00:00 +0000

Heck's Blog

团队 Git 使用规范

[评论] 团队 Git 使用规范