Git Commit 规范实践：Angular Commit 规范 + Commitlint 自动化验证

在日常开发中，规范化的 Git Commit 信息不仅能让代码变更历史清晰可读，还能方便自动化生成 CHANGELOG、快速定位问题。本文将详细介绍 Angular Commit 规范，并结合 Commitlint 实现 Commit 信息的自动化验证。

---

一、为什么需要规范 Commit 信息？

• 提高可读性：清晰的 Commit 信息让团队成员快速了解变更内容
• 自动化生成 CHANGELOG：通过规范化的提交信息，可以自动生成版本发布日志
• 快速定位问题：通过类型和范围快速过滤相关提交
• 规范团队协作：统一提交格式，减少沟通成本

---

二、Angular Commit 规范详解

Angular Commit 规范是目前最流行的提交规范之一，其格式如下：

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

2.1 Header（必填）

Header 部分包含 type、scope 和 subject：

Type（必填）

用于说明 commit 的类别，常用类型包括：

类型	说明
feat	新增功能/特性
fix	修复 bug
docs	文档更新
style	代码样式调整（不影响代码运行）
refactor	代码重构（既不是新增功能，也不是修复 bug）
perf	性能优化
test	测试相关
chore	构建过程或辅助工具的变动
revert	回退提交
build	构建系统或外部依赖变更
ci	CI 配置和脚本变更

Scope（可选）

用于说明 commit 影响的范围，例如：component、service、utils 等。

Subject（必填）

对变更的简短描述，要求：

• 使用祈使句，现在时态
• 首字母小写
• 不以句号结尾
• 不超过 50 个字符

示例：

feat(user): add user login function
fix(api): fix token expiration issue
docs: update README installation guide

2.2 Body（可选）

Body 是对本次提交的详细描述，可以包括：

• 变更的动机
• 与之前行为的对比
• 相关的 Issue 链接

示例：

fix(api): fix token expiration issue

The previous token refresh logic didn't handle concurrent requests properly.
Now using a queue to manage multiple refresh attempts.

Closes #123

2.3 Footer（可选）

Footer 主要用于两种情况：

1. Breaking Changes（重大变更）

   feat(api): change user authentication method

   BREAKING CHANGE: The authentication endpoint has been changed from /auth to /api/auth.

2. 关闭 Issue

   fix(api): fix login error

   Closes #456, #789

---

三、使用 Commitizen 辅助生成 Commit（可选）

Commitizen 是一个交互式的 Commit 信息生成工具，可以帮助开发者按照规范生成 Commit 信息。

安装

# 全局安装
npm install -g commitizen

# 或在项目中安装
npm install --save-dev commitizen

初始化

# 使用 Angular 适配器
commitizen init cz-conventional-changelog --save-dev --save-exact

使用

# 替代 git commit
git cz

---

四、使用 Commitlint 验证 Commit 信息

Commitlint: https://github.com/conventional-changelog/commitlint 用于验证 Commit 信息是否符合规范。

4.1 安装

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

4.2 创建配置文件

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

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'chore',
        'revert',
        'build',
        'ci'
      ]
    ],
    'subject-case': [0], // 不限制 subject 大小写
    'subject-max-length': [2, 'always', 100]
  }
};

4.3 配置 Husky

使用 Husky 在 Git Hook 中自动执行 Commitlint：

# 安装 Husky（如果未安装）
npm install --save-dev husky

# 启用 Husky
npx husky install

创建 commit-msg Hook：

# 创建 .husky/commit-msg 文件
cat > .husky/commit-msg << 'EOF'
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no-install commitlint --edit "$1"
EOF

# 添加执行权限
chmod +x .husky/commit-msg

4.4 配置 package.json (可选)

在 package.json 中添加commitlint脚本：

{
  "scripts": {
    "prepare": "husky install",
    "commitlint": "commitlint --config commitlint.config.js"
  }
}

---

五、完整配置示例

项目结构

project/
├── .husky/
│   └── commit-msg
├── commitlint.config.js
├── package.json
└── .gitignore

5.1 commitlint.config.js

commitlint.config.js（最小化配置）

module.exports = {
  extends: ['@commitlint/config-conventional']
};

commitlint.config.js 更多配置

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',     // 新功能
        'fix',      // 修复
        'docs',     // 文档
        'style',    // 样式
        'refactor', // 重构
        'perf',     // 性能
        'test',     // 测试
        'chore',    // 构建过程或辅助工具
        'revert',   // 回退
        'build',    // 构建系统
        'ci'        // CI 配置
      ]
    ],
    'type-case': [2, 'always', 'lower-case'],
    'type-empty': [2, 'never'],
    'scope-empty': [0],
    'scope-case': [2, 'always', 'lower-case'],
    'subject-empty': [2, 'never'],
    'subject-max-length': [2, 'always', 100],
    'header-max-length': [2, 'always', 100],
    'body-leading-blank': [2, 'always'],
    'footer-leading-blank': [2, 'always']
  }
};

5.2 .husky/commit-msg

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no-install commitlint --edit "$1"

---

六、验证效果

✅ 合规的 Commit

git commit -m "feat(user): add user registration function"
# 通过验证 ✅

git commit -m "fix(api): resolve timeout issue when fetching data"
# 通过验证 ✅

git commit -m "docs: update API documentation"
# 通过验证 ✅

❌ 不合规的 Commit

git commit -m "update code"
# ❌ 错误：type 缺失

git commit -m "Feat: add function"
# ❌ 错误：type 应该小写

git commit -m "feat(user) add function"
# ❌ 错误：缺少冒号

---

七、常见问题与解决方案

Q1: Husky 命令无法执行？

# 确保 Husky 已正确安装
npm install --save-dev husky
npx husky install

# 检查 .husky 目录是否有执行权限
chmod +x .husky/*

Q2: commitlint 报错 "config cannot be loaded"？

# 检查配置文件格式
# 确保 commitlint.config.js 语法正确
# 或使用 .commitlintrc.json 替代

Q3: 如何跳过 commitlint 验证？

# 不推荐，仅在紧急情况使用
git commit -m "fix: emergency fix" --no-verify

---

八、总结

通过 Angular Commit 规范和 Commitlint 自动化验证，我们可以：

1. ✅ 统一团队的 Commit 信息格式
2. ✅ 自动化验证 Commit 信息合法性
3. ✅ 方便生成清晰的 CHANGELOG
4. ✅ 提高代码审查和问题定位效率

建议团队成员都遵循此规范，并在 CI/CD 流程中也加入 Commitlint 验证，确保所有提交都符合规范。

---

参考资料

• Angular Commit Guidelines
• Commitlint 官方文档
• Commitizen 官方文档
• Conventional Commits 规范

---

规范化 Commit 是团队协作的基础，建议从项目初期就开始执行，养成良好习惯！

如果本文对您有帮助，欢迎点赞收藏，有任何问题也可以在评论区交流讨论！😊