Git 提交规范：Husky + Commitlint 实践

Husky 和 Commitlint 的价值，不是“让提交更好看”，而是把团队最基础的一条协作规则自动化：每次提交都必须说清楚改动类型和范围。这样 changelog、代码审查、回滚定位和发布记录都会更稳定。

目录

• 这套方案解决什么问题
• Commitlint 负责什么
• Husky 负责什么
• 最小可用配置
• 为什么建议先约束 commit-msg，而不是先堆 pre-commit
• 分支策略不要比团队成熟度更复杂
• 什么时候值得进一步扩展
• 常见误区
  • 1. 误以为 Husky 就是 commitlint
  • 2. 误以为规范提交信息等于规范提交粒度
  • 3. 误把旧教程当最新版
• 结论
• 参考资料

这套方案解决什么问题

如果团队长期出现这些情况：

• 提交信息全是 update、fix bug
• 一次提交混很多无关改动
• 发布前很难梳理本次到底改了什么
• 想做 changelog、semantic-release、自动版本语义升级却没有可靠输入

那么最值得先自动化的，通常不是复杂分支模型，而是提交信息约束。

Commitlint 负责什么

Commitlint 本身不替你生成提交信息，它负责校验格式是否符合规则。

常见格式：

<type>(scope): <subject>

例如：

git commit -m "feat(auth): add Google login"
git commit -m "fix(search): handle empty keyword"

当前 commitlint 官方文档推荐通过配置文件扩展 @commitlint/config-conventional，这是最常见的起点。

Husky 负责什么

Husky 的作用是把校验接到 Git hook 上，让提交发生时自动执行。

当前 Husky 官方 get started 文档里，推荐的初始化方式是：

npm install --save-dev husky
npx husky init

官方文档说明 husky init 会自动创建 .husky/ 脚本并更新 package.json 里的 prepare。这比旧教程里手动 husky install、husky add 的写法更适合现在的新项目。

最小可用配置

安装：

npm install --save-dev husky @commitlint/cli @commitlint/config-conventional
npx husky init

创建 commitlint.config.js：

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

然后把 .husky/commit-msg 改成：

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

这套结构足够覆盖大多数中小团队。

为什么建议先约束 commit-msg，而不是先堆 pre-commit

很多项目一上来就在 pre-commit 里塞：

• lint
• test
• typecheck
• format
• build

结果是本地提交流程又慢又脆，大家反而想跳过 hook。相比之下，commit-msg 的成本极低、收益直接，非常适合作为第一步。

代码格式和测试校验当然也重要，但更适合按仓库规模逐步加，而不是一开始把所有动作都挂到一次提交上。

分支策略不要比团队成熟度更复杂

这篇旧文之前把重点放在“精简 Git Flow”。实际落地里，更常见也更够用的是：

• main：可发布
• feature/*：新功能
• fix/*：问题修复

团队规模不大时，不必为了“看起来专业”强上 develop、release/*、hotfix/* 全家桶。提交规范和小步提交，比分支命名花样更重要。

分支基础动作可以先配合 Git 入门工作流 使用。

什么时候值得进一步扩展

当你已经稳定执行 Conventional Commits 后，再考虑继续加：

• 自动生成 changelog
• semantic-release
• CI 中重复校验 commit message
• PR 模板
• lint-staged 做按暂存文件粒度的校验

顺序应该是：

1. 先把提交信息标准化
2. 再把标准接入 hook
3. 最后再把它接到发布自动化链路

常见误区

1. 误以为 Husky 就是 commitlint

不是。Husky 是 hook 管理器，Commitlint 是提交信息校验器。

2. 误以为规范提交信息等于规范提交粒度

格式正确不代表提交拆得好。feat: update many files 依然可能是坏提交。

3. 误把旧教程当最新版

Husky 当前官方文档更推荐 npx husky init。如果还在照搬旧版 husky install / husky add 教程，最好先确认版本背景。

结论

• Commitlint 负责定义并校验提交格式。
• Husky 负责把这条校验挂到本地 Git 生命周期。
• 对多数团队，先上 commit-msg 约束是性价比最高的一步。
• 复杂分支模型不是前提，清晰提交历史才是。

参考资料

• Husky Get Started
• commitlint Configuration