Commitlint 依赖 commit-msg 钩子而非 VSCode 插件，需通过 husky 安装并配置可执行的 .husky/commit-msg 文件，否则校验不生效；默认仅校验 header，body/footer 需显式配置规则。
Commitlint 在 VSCode 里不会自动生效——它根本不依赖 VSCode 插件，而是靠 commit-msg 钩子拦截 git commit 流程。装了插件但没配钩子，等于没装。
commit-msg 钩子没装或不可执行，commitlint 就是摆设
你改了 commitlint.config.js、加了 @commitlint/config-conventional，但 git commit -m "test" 还是秒过？先别调规则，检查钩子本身是否真在跑：
-
npx husky install必须执行，否则.husky/目录压根不创建 -
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'必须手动运行；husky 初始化（如npx husky init）不会自动加这行 - 检查
.husky/commit-msg文件是否存在，且权限为可执行：chmod +x .husky/commit-msg；Windows 用户用 Git Bash 时极易漏这步 - 用
git commit --allow-empty -m "test"测试：如果没报类似subject may not be empty的错误，说明钩子根本没触发
VSCode 提交面板能触发 commit-msg，但有硬性前提
VSCode 源代码管理视图里的提交框，底层调的是 git commit 命令，所以只要 .husky/commit-msg 存在且可执行，它就会走钩子流程。但以下情况会断开链路：
batch-git-url-replace
下载
批量替换指定目录下所有 Git 仓库的远程地址（remote URL）。 当用户需要将 Git 仓库从一个服务器迁移到另一个服务器时使用。 触发词：git remote 替换、git url 批量修改、git 仓库迁移、更换 git 地址、批量修改 remote url。
- 用了 Git Graph、Git Tree 等第三方插件直接调
git commit，某些插件绕过 shell 环境，导致钩子不执行 - 终端里用
git commit -m "xxx"能触发，但此时$1是临时文件路径，commitlint --edit依赖该路径读取内容；若用-m提交，commitlint实际只校验header行，body和footer默认不参与校验 - 别指望 VSCode 的“提交模板”（
.gitmessage）能替代校验——它只是预填充文本，填错照样能过；commitlint才是守门员
commitlint 默认只校验 header，body/footer 需显式配置规则
很多人写了 feat(auth): add login validation，后面还跟了三段 body 和 footer，结果依然不报错——因为默认规则集（如 @commitlint/config-conventional）只强制要求 header 格式，body 和 footer 完全可选且无约束。
- 要校验
body是否为空或长度不足，加规则：body-min-length: [2, 'always', 10] - 要强制
footer包含closes #xxx，需自定义规则，例如用footer-pattern匹配正则/^closes #\d+$/ -
header-max-length默认是 72 字符（不是 7），但截至 2026 年 6 月，主流配置仍建议设为 100；注意这个值校验的是整行（包括type(scope):），不是仅subject
commitlint 规则写对了，但提交还是通过？检查 husky 是否被跳过
常见但容易被忽略的断点：
-
package.json中没有"postinstall": "husky install"，团队成员npm install后钩子不会自动激活 - 项目根目录下没有
package.json（比如纯 Python 项目），husky 无法识别为 Node.js 项目，默认不启用钩子；此时需手动创建空package.json或改用simple-git-hooks - VSCode 终端启用了
git别名（如alias.ci=commit -m），而别名未继承 shell 环境变量或钩子路径，导致commit-msg不执行
最稳的验证方式：关掉所有 VSCode 插件，只用内置终端执行 git commit（不带 -m），看编辑器打开后保存退出时是否报错。这一步绕过了所有图形化层干扰，直击钩子本质。
