Git 工作流与协作规范

主流 Git 工作流对比

选择合适的 Git 工作流是团队协作的基石。不同的项目规模和发布节奏适合不同的策略，以下是三种最常见的工作流。

Git Flow

Git Flow 是最经典的分支模型，适合有计划性发布周期的项目。它维护两个长期分支：main（生产代码）和 develop（开发集成分支）。功能开发在 feature/* 分支进行，完成后合并回 develop；发布时从 develop 拉出 release/* 分支，测试通过后合并到 main 和 develop；紧急修复通过 hotfix/* 分支从 main 拉出。

# Git Flow 典型操作
git checkout -b feature/user-auth develop
# ... 开发完成后 ...
git checkout develop
git merge --no-ff feature/user-auth
git branch -d feature/user-auth

GitHub Flow

GitHub Flow 更简洁，只有一个长期分支 main。所有开发在功能分支上进行，通过 Pull Request 合并。适合持续部署的 Web 项目。

# GitHub Flow 操作流程
git checkout -b feature/dark-mode main
# ... 开发并提交 ...
git push -u origin feature/dark-mode
# 然后在 GitHub 上创建 Pull Request 进行 Code Review

Trunk-Based Development

主干开发要求所有开发者频繁地向 main（或 trunk）分支提交代码，功能开关（Feature Flag）替代分支来控制未完成功能。这种方式要求成熟的 CI/CD 基础设施和良好的自动化测试覆盖。

分支命名规范

统一的分支命名能让团队成员快速理解每个分支的用途：

# 推荐的分支命名格式
feature/JIRA-1234-add-user-profile
bugfix/JIRA-5678-fix-login-error
hotfix/JIRA-9012-patch-security-issue
release/v2.1.0
chore/update-dependencies

规则很简单：类型前缀 + 任务编号 + 简短描述，使用短横线分隔单词，全部小写。

Conventional Commits 提交规范

Conventional Commits 是一种标准化的提交消息格式，配合工具可以自动生成 CHANGELOG 和语义化版本号。

# 提交消息格式
# <type>(<scope>): <subject>
#
# <body>
#
# <footer>

# 示例
feat(auth): add JWT token refresh mechanism

Implement silent token refresh 5 minutes before expiration.
The refresh logic uses a dedicated axios interceptor.

Closes #1234

# 常用 type
# feat:     新功能
# fix:      修复 Bug
# docs:     文档变更
# style:    代码格式（不影响功能）
# refactor: 重构（不新增功能也不修复 Bug）
# perf:     性能优化
# test:     测试相关
# chore:    构建工具或辅助工具变动

推荐使用 commitlint + husky 在提交时自动校验格式：

# 安装
npm install -D @commitlint/cli @commitlint/config-conventional husky

# commitlint.config.js
export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'subject-max-length': [2, 'always', 80],
  }
}

# 配置 husky 钩子
npx husky init
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

Code Review 最佳实践

Code Review 不仅仅是找 Bug，更是知识共享和代码质量保障的关键环节。以下是推荐的做法：

控制 PR 体积 — 单个 PR 不超过 400 行变更，过大的 PR 很难得到有效审查。
写好 PR 描述 — 说明"为什么"而不仅是"做了什么"，关联相关 Issue。
自查清单 — 提交前自行检查：是否有调试代码、是否更新了测试、是否需要文档更新。
建设性反馈 — 评论时区分"必须修改"（Blocker）和"建议改进"（Suggestion），避免模糊的评论。
及时响应 — 目标在 24 小时内完成首轮审查。

Merge vs Rebase

这是一个经典争论。简明的建议是：

# 场景一：将功能分支合并到主分支
# 推荐使用 merge --no-ff，保留完整的功能分支历史
git checkout main
git merge --no-ff feature/user-auth

# 场景二：功能分支同步主分支的最新变更
# 推荐使用 rebase，保持线性历史
git checkout feature/user-auth
git rebase main

# 如果 rebase 过程中出现冲突
git rebase --continue  # 解决冲突后继续
git rebase --abort     # 放弃 rebase

冲突解决策略

冲突是团队协作中不可避免的，好的习惯可以减少冲突的发生频率和解决成本。

# 预防冲突的策略
# 1. 频繁同步主分支
git fetch origin main
git rebase origin/main

# 2. 小步提交，减少单次修改范围

# 3. 解决冲突时使用可视化工具
git mergetool  # 配置 VSCode 作为合并工具
# git config --global merge.tool vscode
# git config --global mergetool.vscode.cmd 'code --wait $MERGED'

# 4. 复杂冲突时查看完整上下文
git log --merge --left-right --cherry-pick
git diff HEAD...MERGE_HEAD

.gitignore 实用技巧

# 前端项目 .gitignore 推荐配置
node_modules/
dist/
.env.local
.env.*.local
*.log

# 编辑器
.vscode/settings.json
.idea/

# 系统文件
.DS_Store
Thumbs.db

# 忽略所有 .js.map 文件
*.js.map

# 但保留特定目录下的文件（使用 ! 取反）
!src/config/default.json

小结

没有放之四海而皆准的 Git 工作流。小型团队可以从 GitHub Flow 起步，随着团队和项目规模增长再考虑更严格的流程。无论选择哪种工作流，最重要的是团队达成共识并一致执行。规范的核心目的不是限制自由，而是减少协作摩擦，让开发者把精力集中在编写代码本身。