commitlint不生效的根源是commit-msg钩子未安装或未触发；需用husky安装钩子、检查文件权限、确保vscode提交走git命令行流程，并验证配置加载顺序与模板格式是否符合解析规则。
commitlint 不生效？先确认它有没有被真正触发
很多人配完 commitlint.config.js 和依赖，一提交还是没报错——根本原因往往是 commit-msg 钩子压根没装上。commitlint 本身只是校验器，不挂钩子就等于没通电的灯泡。
- 必须手动安装
husky（或其他钩子管理工具），并初始化钩子：npx husky install，再添加：npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"' - 检查
.husky/commit-msg文件是否存在、是否可执行（chmod +x）；Windows 用户若用 Git Bash，这点尤其容易漏 - VSCode 内置的提交面板（Source Control 视图里的输入框）默认走的是 Git 命令行流程，只要钩子存在就会触发；但如果你用第三方插件（如 Git Graph）直接调用
git commit，也得确保它没绕过钩子
VSCode 提交模板怎么和 commitlint 联动才不打架
模板填得再规范，如果格式不符合 commitlint 的解析预期，照样被拒。关键不是“写得全”，而是“结构对”。commitlint 默认只认第一行（header），后面 body 和 footer 是可选但有强规则约束的。
- 在项目根目录建
.gitmessage，内容建议留空行分隔：type(scope): subject <p>body (optional)</p><p>footer (optional)</p><div class="aritcle_card flexRow artxards"> <div class="artcardd flexRow"> <a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill1675" title="VSCode"><img src="https://img.php.cn/upload/skill/000/000/081/178842972858328.jpg" alt="VSCode" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a> <div class="aritcle_card_info flexColumn"> <a rel="nofollow" href="/xiazai/skill1675" title="VSCode" class="overflowclass">VSCode</a> <p class="overflowclass">避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。</p> </div> <a rel="nofollow" href="/xiazai/skill1675" title="VSCode" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div>
- 执行：
git config commit.template .gitmessage（仅当前项目生效，比全局配置更安全） - commitlint 的
body-leading-blank规则默认开启，意味着 header 和 body 之间**必须有一个空行**；模板里少这行，VSCode 自动填充后你删掉空行，提交就会失败 - 别在模板里预设
feat:这类前缀——类型要由开发者自己选，commitlint 才能校验枚举值；模板只负责占位和引导结构
规则改了但不生效？检查 extends 和 rules 的加载优先级
很多人复制粘贴配置后发现 type-enum 没限制住 chore，或 header-max-length 形同虚设——问题常出在配置继承链被意外覆盖。
-
extends: ['@commitlint/config-conventional']会加载一套完整规则，你自定义的rules是**叠加**而非替换；想禁用某条规则，得显式设为[0]，比如：'subject-case': [0] - 避免在
package.json里同时写commitlint字段和单独的commitlint.config.js，后者优先级更高，前者可能被忽略 - 修改配置后，**必须重新提交一次**才能验证（不是重启 VSCode）；因为校验发生在
git commit过程中，和编辑器无关
为什么 VSCode 提交时没提示、也没报错？查这三个地方
不是配置失效，而是整个链路断在了前端感知层。VSCode 不主动弹窗告诉你“commitlint 拒绝了”，它只忠实地把 Git 的退出码（非零）转成静默失败。
- 打开 VSCode 终端，手动运行：
echo "test" | npx commitlint，看是否输出错误；如果报Cannot find module '@commitlint/config-conventional'，说明依赖没装对或路径不对 - 在
.husky/commit-msg里临时加一行：echo "DEBUG: commit-msg triggered"，然后提交，看终端是否有该输出——没有就证明钩子根本没跑 - VSCode 状态栏右下角点 Git 图标 → “Open Git Log”，翻到最近几条，找含
commit-msg的记录；如果看到husky - commit-msg hook exited with code 1，说明 commitlint 已介入，只是你没看到具体错误文本（错误实际输出在 Git CLI 中，VSCode 不显示）
最容易被忽略的一点：commitlint 校验的是最终生成的提交信息字符串，不是你在 VSCode 输入框里看到的实时内容。换行、空格、中文标点这些肉眼难辨的细节，往往就是卡点。
