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>

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

Footer 主要用于两种情况：

Breaking Changes（重大变更）

feat(api): change user authentication method

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

fix(api): fix login error

Closes #456, #789

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

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

安装

bash 复制代码

# 全局安装
npm install -g commitizen

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

初始化

bash 复制代码

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

使用

bash 复制代码

# 替代 git commit
git cz

四、使用 Commitlint 验证 Commit 信息

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

4.1 安装

bash 复制代码

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

4.2 创建配置文件

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

javascript 复制代码

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：

bash 复制代码

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

# 启用 Husky
npx husky install

创建 commit-msg Hook：

bash 复制代码

# 创建 .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脚本：

json 复制代码

{
  "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（最小化配置）

javascript 复制代码

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

commitlint.config.js 更多配置

javascript 复制代码

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

bash 复制代码

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

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

六、验证效果

✅ 合规的 Commit

bash 复制代码

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

bash 复制代码

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

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

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

七、常见问题与解决方案

Q1: Husky 命令无法执行？

bash 复制代码

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

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

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

bash 复制代码

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

Q3: 如何跳过 commitlint 验证？

bash 复制代码

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

八、总结

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

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

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

参考资料

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

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

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

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

二、Angular Commit 规范详解

2.1 Header（必填）

Type（必填）

Scope（可选）

Subject（必填）

2.2 Body（可选）

2.3 Footer（可选）

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

安装

初始化

使用

四、使用 Commitlint 验证 Commit 信息

4.1 安装

4.2 创建配置文件

4.3 配置 Husky

4.4 配置 package.json (可选)

五、完整配置示例

项目结构

5.1 commitlint.config.js

5.2 .husky/commit-msg

六、验证效果

✅ 合规的 Commit

❌ 不合规的 Commit

七、常见问题与解决方案

Q1: Husky 命令无法执行？

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

Q3: 如何跳过 commitlint 验证？

八、总结

参考资料