如何规范团队 Git commit message 提交信息格式

团队协作中，最推荐采用约定式提交规范（Conventional Commits），配合自动化工具强制检查，适合需要长期维护且有外部利益相关者监督的项目。

先说结论：统一格式是为了让机器和人都能读懂变更记录，减少沟通成本。

适合：多成员协作、需要自动生成 CHANGELOG 的项目
先看：提交类型（type）和影响范围（scope）的定义是否清晰
建议：使用 Commitizen 或 Husky 在提交前拦截不规范信息

标准格式结构

标准的提交信息格式由 Header、Body 和 Footer 组成，其中 Header 是必需的。基本结构如下：

<type>(<scope>): <subject>

<body>

<footer>

示例：

feat(user): 增加用户登录接口

- 新增 login 方法
- 修改 auth 中间件

BREAKING CHANGE: 旧版 token 失效

本地 Git 模板配置（轻量级）

若不引入复杂工具，可修改 Git 配置设置本地提交模板，提醒开发者填写规范信息。

1. 创建模板文件 ~/.gitmessage：

# <type>(<scope>): <subject>
# type: feat, fix, docs, style, refactor, test, chore
# subject: 50 字以内，动宾结构

2. 关联 Git 配置：

git config `--global` commit.template ~/.gitmessage

3. 验证：执行 git commit 时会自动打开编辑器加载模板内容。

工程化自动校验（推荐团队落地）

仅靠自觉难以维持规范，建议通过 Husky + Commitlint 在提交阶段强制拦截。

1. 安装依赖

npm install -D commitizen cz-conventional-changelog husky commitlint @commitlint/config-conventional

2. 配置 Commitlint

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

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

3. 配置 Commitizen（可选交互式）

在 package.json 中添加配置，支持 npm run commit 向导：

"config": {
  "commitizen": {
    "path": "cz-conventional-changelog"
  }
}

4. 初始化 Husky 钩子

npx husky install
npx husky add .husky/commit-msg 'npx `--no` -- commitlint `--edit` $1'

配置完成后，当提交信息不符合规范时，Git 将阻止 commit 并报错。

验证与排查

1. 查看提交历史

运行 git log `--oneline`，观察提交信息是否整齐划一，能否一眼区分功能开发和 bug 修复。

2. 手动校验当前提交

若不确定当前 commit 是否符合规范，可运行：

npx commitlint `--from`=HEAD~1 `--to`=HEAD

3. 过滤特定范围

使用 git log `--grep` 命令配合 scope 关键词，验证能否快速定位特定模块的变更历史：

git log `--grep`="feat(user)" `--oneline`

4. 生成更新日志

尝试使用基于约定式提交的工具（如 standard-version）生成 CHANGELOG，检查是否能正确提取 feat 和 fix 类型的变更内容。

常见落地坑点

主题行过长：Header 中的 subject 部分建议控制在 50 字以内，任何一行最好不要超过 72 个字符，避免在终端或代码托管平台上显示换行混乱。
用词模糊：避免使用“优化”、“调整”等 vague 词汇，应具体说明做了什么，例如“修复用户注册时的空指针异常”。
忽略 Body 和 Footer：对于重大功能或复杂重构，务必利用 Body 补充变更原因和副作用说明；若有破坏性变更（BREAKING CHANGE），必须在 Footer 中声明。
合并提交干扰：Git Merge 产生的默认提交信息往往不符合规范，建议在 CI 中配置忽略 merge commit 或要求使用 `--no-ff` 并手动修改信息。

笙亿网络策划