Git 代码管理规范指南
1. 前言与目的
在多人协作的软件研发过程中，Git 代码管理是保证项目有序迭代、快速定位问题、顺利发布版本的基础。本规范旨在统一团队的分支命名、环境对应关系及提交行为，降低协作成本，避免因分支混乱、提交随意导致的线上故障或版本回滚困难。
所有开发人员、测试人员及运维人员均应遵守本规范。
2. 分支命名规范
2.1 常驻分支（永久存在）
| 分支名 | 说明 | 生命周期 |
|---|---|---|
master |
主分支，始终对应生产环境（PRO）。该分支的每一次提交都应是一个可发布的稳定版本，禁止直接提交代码。 | 永久 |
develop |
开发分支，对应开发环境（DEV）。包含最新已完成并验证的功能代码，是集成与日常开发的基础。 | 永久 |
2.2 临时分支（按需创建，合并后删除）
| 分支类型 | 命名格式 | 示例 | 说明 |
|---|---|---|---|
feature |
feature/功能模块 或 feature/模块_开发者 |
feature/user_login feature/cart_module |
从 develop 拉出，用于新功能开发。完成后合并回 develop。 |
test |
test（固定名称） |
test |
对应功能验收测试环境（FAT），供测试人员验证，外部用户无法访问。 |
release |
release（固定名称） |
release |
对应用户验收测试环境（UAT） ，预上线最终验证。仅允许修复阻断性 Bug，验证后合入 master 并打标签。 |
hotfix |
hotfix（或带日期/编号） |
hotfix |
从 master 拉出，紧急修复生产问题。修复后必须同时合并回 master 和 develop（以及当前 release）。 |
重要原则 ：除
master和develop外，所有临时分支在完成任务且合并后应及时删除，避免分支堆积。禁止直接向master/develop提交代码。
3. 分支与环境对应关系（完整说明）
| 分支 | 环境名称 | 缩写 | 是否可被外部访问 | 主要用途 |
|---|---|---|---|---|
master |
生产环境 | PRO | 是 | 对外提供服务的稳定版本 |
develop |
开发环境 | DEV | 仅内网/开发者 | 开发者日常调试、集成最新代码 |
feature/* |
本地或开发环境 | DEV（个人） | 否 | 实现新特性，不对外暴露 |
test |
功能验收测试环境 | FAT | 测试人员 | 功能测试、验收、Bug 复测 |
release |
用户验收测试环境 | UAT | 预发布验证人员 | 预上线模拟、回归测试、UAT 验证 |
hotfix |
生产环境（修复中） | PRO | 否 | 线上紧急问题修复，修复后重新部署 |
注意 ：
test分支虽然可被访问，但仅面向内部测试团队；feature分支即使远程协作，也属于开发阶段，不占用正式环境路由。
4. 分支操作流程详解
新功能开发流程
bash
# 1. 从 develop 拉取最新代码
git checkout develop
git pull origin develop
# 2. 创建 feature 分支
git checkout -b feature/user_module
# 3. 在 feature 分支上开发、提交
git add .
git commit -m "feat: 完成用户模块基本功能"
# 4. 推送远程（便于协作）
git push origin feature/user_module
# 5. 通过 MR/PR 将 feature 合并到 develop（禁止直接合并）
# 6. 删除 feature 分支（本地+远程）
git branch -d feature/user_module
git push origin --delete feature/user_module测试与发布流程
· 功能测试：将 develop 或特定 feature 合并到 test 分支，部署至 FAT 环境供测试团队验证。
· 预发布：develop 功能稳定后，拉出 release 分支，部署至 UAT 环境。
注意：release 分支上只允许修复影响发布的 Bug，禁止新增功能。
· 生产发布：release 验证通过 → 合并到 master 并打版本标签（如 v1.2.0）→ 部署至 PRO 环境。
同时将 release 上的修复同步合并回 develop。
紧急修复流程（hotfix）
bash
# 1. 从 master 拉取 hotfix 分支
git checkout master
git pull origin master
git checkout -b hotfix
# 2. 修复问题，提交
git add .
git commit -m "fix: 修复支付接口超时问题"
# 3. 合并到 master（生产）
git checkout master
git merge hotfix
git tag v1.2.1
# 4. 合并到 develop（同步修复）
git checkout develop
git merge hotfix
# 5. 删除 hotfix 分支
git branch -d hotfix若当前存在未上线的 release 分支：hotfix 还必须合并到该 release 分支，以避免上线时丢失紧急修复。
5. 单次提交规范
5.1 提交的基本原则
- 单一职责：一次提交只解决一个问题，只能包含同一类别的改动（不能同时包含"新增功能"和"格式调整"）。
- 粒度适中 ：一次提交改动逻辑点不要超过 3 个，便于代码审查与回滚。
- 信息明确：提交信息能清晰表达本次改动的意图。
5.2 提交类型标识（Conventional Commits 风格）
| 标识 | 含义 | 示例 |
|---|---|---|
feat |
新增功能 | feat: 增加短信登录接口 |
fix |
修复 Bug | fix: 修复订单金额计算错误 |
docs |
仅文档更改 | docs: 更新 API 文档 |
style |
代码格式、空白、分号等（不影响逻辑） | style: 统一缩进为2空格 |
refactor |
重构（既不是新功能也不是修复） | refactor: 抽取公共验证方法 |
perf |
性能优化 | perf: 优化首页加载速度 |
test |
增加或修改测试代码 | test: 补充购物车单元测试 |
chore |
构建过程、辅助工具或库的更改 | chore: 升级 webpack 到 5.x |
5.3 提交信息格式
格式：<type>: <简短描述>，随后可跟空行和详细说明。
示例：
feat: 支持用户头像上传
- 使用 OSS 存储
- 前端增加裁剪功能
- 后端接口增加校验
5.4 提交不符合规范如何修正？
| 场景 | 命令 |
|---|---|
| 最后一次提交信息写错 | git commit --amend -m "新的提交信息" |
| 最后一次提交包含了不该有的改动，想完全重来（未推送） | git reset --hard HEAD~1 然后重新提交 |
| 已经推送但需修改提交信息 | git commit --amend -m "新信息" → git push --force-with-lease（谨慎使用） |
团队建议 ：在
develop、release、master分支上禁止使用--force；个人feature分支可酌情使用。
6. 最佳实践与避免事项
6.1 推荐做法
- 保持分支干净：每完成一个功能，立即合并并删除源分支。
- 频繁拉取上游代码 ：每天开始工作前执行
git pull origin develop，减少冲突。 - 使用 MR/PR 机制 ：要求至少一位同事审查后再合并到
develop或master。 - 与 CI/CD 联动 ：对
master、release、test分支的推送自动触发构建和部署。
6.2 禁止事项
- 直接向
master或develop提交代码（即使是一个小修改也必须通过合并请求）。 - 在
release分支上开发新功能。 - 将未完成或未测试的
feature合并到test分支。 - 提交信息使用无意义的词语，如
update、修改代码、fix bug（必须说明具体内容）。
7. 常见问题（FAQ）
Q1：如果同时有多个 feature 需要测试，test 分支如何处理？
A：通常 test 分支只反映当前需测试的代码集合。可将多个 feature 依次合并到 test 进行集成测试，但注意不要互相覆盖。建议使用临时测试分支，如 test/user_module，但最终仍应合并回 test 或 develop。
Q2：hotfix 修复后，如果当前有 release 分支未上线，应该如何处理？
A：hotfix 既要合并到 master，也要合并到 develop，并且还要合并到当前活跃的 release 分支（如果存在），以避免在上线时丢失修复。
Q3：用户反馈线上的 bug，但在 develop 上无法复现，怎么办？
A：直接从 master 拉 hotfix 分支定位修复，修复后按流程合并回所有相关分支。
8. 附录：分支命名速查表
| 用途 | 分支名 | 基于分支 | 合并到 | 环境 |
|---|---|---|---|---|
| 日常开发 | feature/* |
develop |
develop |
DEV（本地） |
| 功能测试 | test |
develop |
（可任意） | FAT |
| 预发布 | release |
develop |
master + develop |
UAT |
| 紧急修复 | hotfix |
master |
master + develop |
PRO |
| 生产稳定版 | master |
- | - | PRO |
| 开发集成分支 | develop |
- | - | DEV |
9. 分支协作示意图
master (生产) <- release (预上线) <- develop (开发) <- feature/* (新功能)
^ ^
| |
+--------- hotfix ------------+ (紧急修复同时合并至 develop)规范强制：所有合并均须通过 PR/MR 审查 + 自动化流水线，禁止绕过。