commitlint 是什么
commitlint 是校验提交信息是否符合约定格式的工具，通常用 @commitlint/cli 搭配 @commitlint/config-conventional 使用，检查类型、作用域、标题长度等是否合规。它既能挂在本地提交钩子上做实时拦截，也能在 CI 里对整段提交区间做全量检查。规则可以逐条覆盖，适配中文团队时一般会放宽标题长度并关闭标题大小写限制。适用于任何使用 Node 工具链的仓库。
基本信息
| 安装 | npm i -D @commitlint/cli @commitlint/config-conventional |
|---|---|
| 配置文件 | commitlint.config.js 中 extends 内置规范 |
| 常用参数 | --from/--to 检查提交区间；--edit 校验钩子传入的信息文件 |
| 运行环境 | Node.js 工具链 |
| 平台 | 本地钩子与 CI 均可使用 |
典型使用场景
- 团队统一提交格式，让变更日志可以自动生成
- 评审前拦截格式不合规的提交，减少返工
- CI 中校验整个 PR 区间的提交信息
- 中文团队需要放宽标题长度或关闭大小写规则
- 新成员环境里通过钩子即时给出格式提示
- 排查发版工具算错版本号，定位到格式不合规的提交
配置示例
配置示例
// commitlint.config.js
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'subject-case': [0], // 关闭标题大小写限制
'header-max-length': [2, 'always', 100], // 标题放宽到 100 字符
},
};命令行使用
命令行使用
npx commitlint --from origin/main --to HEAD --verbose # 校验区间
npx commitlint --edit "$1" # 在提交钩子里校验信息文件
echo 'feat: 支持单点登录' | npx commitlint # 快速自测一条常用规则项
| 规则 | 含义 |
|---|---|
| type-enum | 限定允许的提交类型集合 |
| header-max-length | 标题最大长度 |
| scope-enum | 限定作用域取值范围 |
| subject-empty | 禁止空标题 |
规则可逐条覆盖：例如关闭标题大小写限制、把标题长度放宽到 100，以适配中文团队；改动后先用几条历史提交回测，确认不会大批误报。
把校验结果写成可读提示比直接抛出一长串规则名更有用：CI 里输出失败提交的标题与命中的规则，贡献者照着改就能过。
接入的推荐步骤
- 先安装依赖并写最小配置，extends 官方约定即可
- 本地加提交钩子，让问题在提交瞬间暴露
- CI 中对 PR 区间再跑一次作为兜底
- 按团队习惯覆盖个别规则，并在仓库文档中同步说明
校验失败了别急着 --no-verify 跳过，先看是不是标题超过长度或类型拼写问题，多数情况改一行信息就能通过。