commitlint 是什么
commitlint 校验提交信息是否符合约定格式，例如 Conventional Commits 的 类型(范围): 描述 结构。它通常挂在本地 commit-msg 钩子上，在提交那一刻就拦下不合规的信息，CI 里再兜底校验一次，防止用 --no-verify 绕过。
基本信息
| 校验目标 | 提交信息的结构：type、scope、subject |
|---|---|
| 本地钩子 | commit-msg（配合 husky 等钩子管理工具） |
| 配置方式 | commitlint.config.js，用 extends 继承共享配置 |
| CI 兜底 | 对提交区间做校验，防止绕过钩子 |
| 依赖关系 | 约定稳定后，变更日志与版本号才可自动生成 |
典型使用场景
- 团队统一提交信息格式，回滚与定位改动范围更快
- 自动生成变更日志，按类型分组整理发布说明
- 触发语义化版本号递增与发布流程
- 关联需求编号或问题单号，方便回溯
- 新人入职时用钩子反馈代替口头提醒
配置与钩子
配置与钩子
npm i -D @commitlint/cli @commitlint/config-conventional # 安装 CLI 与共享配置
echo "export default { extends: ['@commitlint/config-conventional'] }" > commitlint.config.js
npx commitlint --from HEAD~1 --to HEAD --verbose # 校验最近一次提交
npx commitlint --edit "$1" # 在 commit-msg 钩子里校验本次信息
# 本地钩子被绕过时，CI 用提交区间做兜底校验提交信息逐段读法
| 片段 | 含义 | 常见错误 |
|---|---|---|
| type | 改动类型，如 feat / fix / docs / chore | 用生造类型，工具与团队词表不匹配 |
| scope | 影响范围，如模块名或目录名 | 范围写法不统一，统计时无法聚合 |
| subject | 一句话描述改动 | 描述写成流水账或只写 update |
| body / footer | 详细说明与需求号、关联问题 | 关键背景只写在聊天记录里 |
提交信息规范是自动化的前提：变更日志生成、版本号递增、发布触发都依赖稳定的类型词表；词表一旦改动，下游脚本要同步更新。
规则要与团队术语对齐：生造类型或苛刻的长度限制会让成员反复被拦，最后习惯性使用绕过参数；制定规则时先看现有提交的实际分布。
钩子只是第一道闸：本地用 commit-msg 钩子即时反馈，CI 再按提交区间校验一次。仓库应提供一键安装脚本（例如安装依赖时自动配置钩子），新成员才不用手工设置环境。