档基于行业最佳实践制定了 Git 分支管理、提交信息规范及团队协作流程。明确了主分支、开发分支等类型定义，采用 Conventional Commits 规范提交信息，并规定了 PR 合并、冲突处理及自动化配置方案。旨在解决版本追溯困难、协作冲突频发等问题，保障生产环境稳定性。
Git 作为分布式版本控制系统，其高效性依赖于团队统一的操作规范。本规范基于行业最佳实践（如 Git Flow、Conventional Commits），结合团队协作场景优化，旨在解决以下问题：
执行原则：规范不是约束，而是协作共识，需团队全员遵守并定期迭代优化。
采用 '主分支 + 支持分支' 的分层模型，明确各分支的职责、生命周期及命名规则，避免分支冗余。
| 分支类型 | 命名规则 | 来源分支 | 合并目标分支 | 生命周期 | 核心职责 |
|---|---|---|---|---|---|
| 主分支 | main | 项目初始化 | 仅接收 hotfix/release | 永久存在 | 存放生产环境代码，始终保持可部署状态 |
| 开发主分支 | develop | 从 main 创建 | 接收 feature，合并到 release | 永久存在 | 整合功能开发代码，作为下一次发布的基础 |
| 功能分支 | feature/[需求 ID]-[功能描述] | develop | 仅合并到 develop | 功能合并后删除 | 开发新功能或迭代优化，隔离开发过程 |
| 紧急修复分支 | hotfix/[BUG ID]-[修复描述] | main | 合并到 main + develop | 修复完成后删除 | 紧急修复生产环境 bug，不影响正常开发流程 |
| 发布分支 | release/[版本号] | develop | 合并到 main + develop | 发布完成后删除 | 预发布测试，仅修复测试中发现的 bug，不新增功能 |
| 测试分支（可选） | test/[测试场景]-[日期] | 任意开发分支 | 不合并到主分支 | 测试完成后删除 | 临时测试特定场景（如性能测试、兼容性测试） |
REQ-2024001、BUG-2024058）。user-login-verify 而非 login）。vX.Y.Z（例：release/v2.3.0）。main 和 develop 分支设置为 保护分支，禁止直接推送（git push），仅允许通过 PR 合并。提交信息是代码历史的 '说明书'，需遵循 Conventional Commits 规范，确保结构化、可追溯，支持自动化工具生成 CHANGELOG。
<类型>[可选作用域]: <简短描述>[可选详细描述][可选脚注]
| 组成部分 | 要求与说明 |
|---|---|
| 类型（必填） | 描述提交的性质，取值范围：\n- feat：新功能（影响次版本号）\n- fix：修复 bug（影响修订号）\n- docs：仅文档修改（如 README）\n- style：代码格式调整（不影响逻辑，如缩进、空格）\n- refactor：代码重构（既非新功能也非修复）\n- test：新增 / 修改测试代码\n- chore：构建流程、工具配置等修改（不影响业务代码） |
| 作用域（可选） | 标注修改涉及的模块 / 组件（如 auth、order-api、pay-service），增强定位精度。 |
| 简短描述（必填） | 50 字以内，简洁说明 '做了什么'，首字母小写，不使用句号结尾（例：'新增短信验证码校验'）。 |
| 详细描述（可选） | 若简短描述不够，补充具体修改点（如 '优化了验证码过期逻辑，从 5 分钟调整为 10 分钟'），换行后开始。 |
| 脚注（可选） | 关联需求 / BUG ID 或关闭 Issue，格式：\n- 关联需求：Relates to REQ-2024001\n- 关闭 BUG：Closes BUG-2024058\n- 关闭 Issue：Fixes #123（GitLab Issue） |
# 新功能提交
feat(auth): 新增短信验证码登录功能
- 开发验证码发送接口（支持 60 秒重试限制）
- 完善登录状态校验逻辑（过期自动登出）
Relates to REQ-2024001
# Bug 修复提交
fix(order): 修复订单超时后状态未同步的问题
解决了支付超时后，订单仍显示'待支付'的问题（原逻辑未监听支付回调超时事件）
Closes BUG-2024058
# 重构提交
refactor(pay): 拆分支付服务冗余代码
将支付验签逻辑抽离为独立工具类，减少重复代码约 200 行
prettier）、lint 检查（如 eslint）、单元测试，确保无语法错误和逻辑问题。dist、node_modules）、IDE 配置（如 .idea，需加入 .gitignore）。# 1. 切换到 develop 分支，拉取最新代码
git checkout develop
git pull origin develop
# 2. 基于最新 develop 创建功能分支（命名见 2.2 节）
git checkout -b feature/REQ-2024001-user-login
为避免分支偏离 develop 过远导致冲突，需定期同步：
# 切换到功能分支
git checkout feature/REQ-2024001-user-login
# 同步 develop 最新代码（推荐使用 rebase 保持线性历史）
git fetch origin develop
git rebase origin/develop
# 若出现冲突，解决后继续 rebase
git add .
git rebase --continue
# 推送更新到远程功能分支（首次推送需关联，后续直接 push）
git push -u origin feature/REQ-2024001-user-login
# 首次
git push origin feature/REQ-2024001-user-login
# 后续
develop。[feature] 功能名称（需求 ID）（例：[feature] 用户登录功能（REQ-2024001））。PR 描述模板（必填）：
## 功能说明
（简要描述实现的功能，关联需求文档链接）
## 测试步骤
1. 步骤 1（如：访问登录页）
2. 步骤 2（如：输入手机号点击发送验证码）
## 变更范围
- 修改文件：（列举核心修改文件）
- 新增依赖：（如有）
## 相关链接
- 需求地址：[REQ-2024001](链接)
- 测试报告：（如有）
develop 历史整洁）。合并后删除远程和本地功能分支：
# 删除远程分支
git push origin --delete feature/REQ-2024001-user-login
# 删除本地分支
git checkout develop
git pull origin develop
# 同步合并后的 develop
git branch -d feature/REQ-2024001-user-login
用于修复 main 分支（生产环境）的紧急 bug，需同时确保修复同步到开发分支。
# 从 main 分支拉取最新代码（生产环境代码）
git checkout main
git pull origin main
# 创建 hotfix 分支
git checkout -b hotfix/BUG-2024058-order-timeout
fix，并关联 BUG ID。main（修复生产）和 develop（同步到开发）。[hotfix] 修复描述（BUG ID）。合并到 main 后，立即打版本标签（见 5.2 节），并删除 hotfix 分支。
用于将 develop 分支的功能发布到生产环境。
# 从 develop 拉取最新代码
git checkout develop
git pull origin develop
# 创建 release 分支（版本号见 5.1 节）
git checkout -b release/v2.3.0
develop 合并或后续迭代）。package.json 的 version 字段）。main 和 develop。main 后，打版本标签并编写发布说明（见 5.2 节）。采用 X.Y.Z 格式，遵循 Semantic Versioning 标准：
X（主版本号）：不兼容的重大变更（如架构重构、API 不兼容），例：3.0.0Y（次版本号）：向后兼容的新功能，例：2.4.0Z（修订号）：向后兼容的问题修复，例：2.3.1版本号递增规则：
Y（如 2.3.0→2.4.0）Z（如 2.3.0→2.3.1）X（如 2.3.0→3.0.0）main 分支打标签，标签格式为 vX.Y.Z（例：v2.3.0）。v2.3.1）。打标签时必须添加描述，说明版本核心变更：
# 创建带注释的标签
git tag -a v2.3.0 -m "v2.3.0：新增用户登录功能，修复订单超时 bug"
# 推送标签到远程
git push origin v2.3.0
| 合并场景 | 推荐合并方式 | 目的 |
|---|---|---|
| feature → develop | Squash Merge | 压缩琐碎提交，保持 develop 历史清晰 |
| hotfix → main / develop | Create a merge commit | 保留完整修复历史，便于追溯生产问题 |
| release → main / develop | Create a merge commit | 保留发布前的测试调整记录 |
禁止操作：
main/develop 分支使用 git push -f（强制推送），防止代码丢失。利用提交信息的结构化特征，通过工具自动生成版本变更记录：
npm install -g standard-version（适用于 Node 项目，其他语言可选用同类工具）。在 main 分支执行（合并 release/hotfix 后）：
standard-version # 自动更新版本号、生成 CHANGELOG、创建标签
git push --follow-tags # 推送版本号和标签
冲突是协作中的正常现象，需通过规范流程减少冲突风险并高效解决。
develop 代码（见 4.1.3 节），及时发现并解决小冲突，避免堆积。config.yaml）尽量设计为可扩展结构，减少直接修改冲突。git rebase 或 git merge 后，Git 会标记冲突文件（含 <<<<<<< HEAD 等标记）。<<<<<<</=======/>>>>>>>）。git add <冲突文件>，继续 rebase/merge 流程，确保代码可运行。通过工具强制规范执行，减少人工成本。
使用 commitlint+husky 检查提交信息格式
# 安装依赖
npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
# 配置 commitlint 规则（根目录创建 commitlint.config.js）
module.exports = {
extends: ['@commitlint/config-conventional']
}
# 配置 husky 钩子（触发 commit 时校验）
npx husky install
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'
配置 pre-commit 钩子，提交前自动执行代码格式化（prettier）、lint（eslint）、单元测试：
npx husky add .husky/pre-commit 'npx lint-staged'# 仅检查暂存区文件
# 配置 lint-staged（package.json）
"lint-staged": {
"*.{js,ts}": ["eslint --fix", "prettier --write"],
"*.{json,md}": ["prettier --write"]
}
main/develop 分支保护：
CI 流程示例（.gitlab-ci.yml）：
stages:
- lint
- test
- build
lint:
stage: lint
script: npm run lint
test:
stage: test
script: npm test
build:
stage: build
script: npm run build
| 问题场景 | 解决方案 |
|---|---|
| 误提交敏感信息（如密钥） | 1. 立即从代码中删除并替换密钥 2. 使用 git filter-branch 清除历史记录3. 通知团队更新密钥 |
| 提交后发现代码错误（未推送） | git commit --amend 修正提交（仅修改最后一次提交） |
| 提交后发现代码错误（已推送） | 新增一个修复提交（类型 fix），不修改历史 |
分支偏离 develop 过远，同步冲突多 | 先创建临时分支备份当前代码，重新从 develop 拉取并 cherry-pick 关键提交 |
| 误删分支 | 从远程分支恢复：git checkout -b 分支名 origin/分支名 |
附录：
.github/PULL_REQUEST_TEMPLATE.md）.gitmessage）通过严格执行本规范，团队可实现 '分支清晰、提交可追溯、协作高效、发布稳定' 的目标，为项目质量提供基础保障。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online