【编译与代码分析记录】04 · Commitlint 与 husky 提交规范

Commitlint 与 husky：Git 提交规范

整理自博客园旧笔记：《Commitlint &husky》（原发布于 2022-09-13）

一、Commitlint

参考资料：https://github.com/conventional-changelog/commitlint/

1.1、是什么

运行 git commit -m 'xxx' 时，用来检查 xxx 是否符合固定格式（Conventional Commits）的工具。

1.2、安装与配置

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

# 生成配置文件（也可以是 .commitlintrc.js）
echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js

本地快速测试：

echo "build: test" | npx commitlint     # 通过无输出
echo "随便写的" | npx commitlint        # 报错，不通过

二、husky：把校验挂到 Git 钩子

husky 继承了 Git 下所有钩子（hooks），触发钩子时可以阻止不合法的 commit、push 等操作。

npm install husky --save-dev

package.json 中引入：

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

工作流程：

1. 执行 git commit -m '测试提交' 时触发 commit-msg 钩子并通知 husky
2. husky 执行 commitlint -E HUSKY_GIT_PARAMS（即 ./node_modules/.bin/commitlint）
3. commitlint 读取 commitlint.config.js 规则，校验提交信息；不通过则输出错误，commit 终止

注意：这是 husky v4 的配置方式（package.json 内嵌）。husky v8/v9 改用 husky init + .husky/ 目录下放置钩子脚本：

npx husky init
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

三、提交规范（Conventional Commits）

3.1、格式

提交格式（注意冒号后有空格）：

git commit -m <type>[optional scope]: <description>

• type：本次提交的改动类型（新功能？修测试？改文档？）
• optional scope：可选的修改范围，标识此次提交涉及哪个模块
• description：一句话描述，言简意赅

3.2、常用 type

类型	描述
build	编译相关修改，如发布版本、对项目构建或依赖的改动
chore	其他修改，如改变构建流程、增加依赖库、工具等
docs	文档修改
feat	新特性、新功能
fix	修改 bug
perf	优化相关，如提升性能、体验
refactor	代码重构
revert	回滚到上一个版本
ci	持续集成修改
style	代码格式修改（不是 css 修改）
test	测试用例修改

3.3、例子

git commit -m 'fix(account): 修复xxx的bug'
git commit -m 'refactor: 重构整个项目'
git commit -m 'feat(user): 新增登录接口'

好处：commit 历史结构化，可由 conventional-changelog 自动生成 CHANGELOG，也便于按 type 人工筛选。