Git 提交规范的详细指南

以下是 Git 提交规范的详细指南，包含结构定义、工具支持和最佳实践，助力团队协作和代码管理：

一、提交信息结构规范

采用 约定式提交（Conventional Commits） 标准，结构如下：

<类型>[可选范围]: <描述>
[空行]
<正文>
[空行]
<尾部>

1. 标题（必填）

• 格式：<type>(<scope>): <description>
• 示例：feat(login): 新增用户登录功能
• 字段说明：
  • 类型（type）：使用明确动词，推荐类型：
    • feat：新功能
    • fix：修复问题
    • docs：文档变更
    • style：代码样式调整（不影响功能）
    • refactor：代码重构
    • test：测试相关
    • chore：构建工具或辅助脚本变更
  • 范围（scope）：可选，用括号包裹，如模块名 user 或文件名 api.js。
  • 描述（description）：简明扼要（≤50字符），以动词开头，如 修复登录超时问题。

2. 正文（可选）

• 内容：详细说明变更背景、原因和结果，每行≤72字符。
• 示例：

  - 添加登录页面和表单验证逻辑
  - 实现与后端的认证接口对接
  - 优化错误提示反馈
  

3. 尾部（可选）

• 关联问题：使用 Closes #123 或 Fixes #456 关联缺陷或需求。
• 破坏性变更：若引入不兼容改动，需以 BREAKING CHANGE: 开头说明。

---

二、工具支持

1. Commitizen（交互式提交工具）

• 安装：

  npm install -g commitizen
  npx commitizen init cz-conventional-changelog --save-dev --save-exact
  

• 使用：

  git cz  # 替代 git commit，按提示选择类型和填写信息
  

2. commitlint（提交信息校验）

• 安装：

  npm install --save-dev @commitlint/config-conventional @commitlint/cli
  

• 配置：在项目根目录创建 commitlint.config.js：

  module.exports = {
    extends: ['@commitlint/config-conventional'],
    rules: {
      'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']],
    },
  };
  

3. husky（Git钩子集成）

• 作用：在提交前自动校验信息格式。
• 配置：在 package.json 中添加：

  {
    "husky": {
      "hooks": {
        "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
      }
    }
  }
  

---

三、最佳实践

1. 分支策略

   • 主分支：main/master 作为生产稳定版。
   • 开发分支：develop 用于整合新功能。
   • 特性分支：从 develop 分出 feature/xxx 分支开发。
   • 修复分支：从 main 分出 hotfix/xxx 紧急修复生产问题。

2. 提交原则

   • 原子性：每次提交仅包含一个逻辑变更。
   • 避免频繁提交：完成一个完整功能或修复后再提交。
   • 关联问题：在提交信息中明确关联需求或缺陷编号。

3. 团队协作

   • 统一规范：团队共同约定规范，使用工具强制执行。
   • 提供模板：为新成员准备提交模板和示例。
   • 代码审查：结合提交信息审查代码变更。

---

四、示例提交信息

1. 新增功能

feat(user): 添加用户注册功能
- 创建注册页面和表单
- 实现邮箱验证逻辑
- 集成短信验证码服务
Closes #98

2. 修复问题

fix(api): 修复订单查询接口超时问题
- 优化数据库查询语句
- 添加接口缓存机制
BREAKING CHANGE: 查询参数 `timeout` 默认值从 3s 调整为 5s

3. 文档变更

docs(README): 更新快速入门指南
- 补充环境配置步骤
- 添加常见问题解答

---

通过遵循以上规范，团队可实现：

• 清晰的变更历史：快速定位问题根源。
• 自动化工具集成：减少人为错误。
• 高效协作：新成员快速融入，减少沟通成本。