如果你的团队已经接入了 Husky你大概率见过这两个钩子文件——.husky/pre-commit和.husky/commit-msg。pre-commit 里跑npx lint-stagedcommit-msg 里写一句npx --no -- commitlint --edit $1。这几乎是前端脚手架生成的标配。但坦白说我经手的几十个仓库里commit-msg 是那个“存在但没人真正懂”的钩子。大家知道它校验提交信息可当它真的拦下一次提交时团队里往往没人能解释清楚$1到底是什么为什么git merge之后它也会蹦出来为什么同一个规则在 Windows 上正常、在同事的 Mac 上就挂这篇文章把我这些年折腾 Husky 和 commit-msg 的经验一次讲清楚包括钩子的触发机制、手写校验脚本的完整思路、接入 commitlint 的配置取舍以及我踩过的那些真实翻车现场。适合已经用上 husky、但想更深入理解提交信息校验原理的前端和后端同学。1. 提交信息才是团队里最容易被低估的长期资产很多团队对 commit message 的态度是“能写就行”“一行随便带过”。但你打开git log看看提交信息在代码被重构、模块被替换之后依然躺在历史里它是整个仓库的审计线索、回滚依据也是 changelog 生成的唯一原料。代码风格错了可以靠 lint 和 review 兜底命名不统一可以由 IDE 辅助唯独提交信息没有“编译器”。它一旦进历史再想批量修就是另一场灾难。我见过一个项目日志里一半是update、fix bug、aaa到了要定位某个功能是什么时候引入的时候我只能靠git blame一行行翻那个痛苦我现在都记得。所以我会跟团队说pre-commit 拦的是“代码质量”commit-msg 拦的是“沟通质量”。前者保证程序能跑后者保证人还能看懂。Husky 在这里做的事情本质上是在提交动作发生前加一道“约定执行器”而 commit-msg 是这道闸门的最后一关。1.1 为什么大多数人对 commit-msg 只停留在“知道”脚手架生成的 commit-msg 文件太短了短到没人愿意认真看。它通常就一行npx --no -- commitlint --edit $1很多人的理解止步于此commit-msg 就是跑一下 commitlint。但这一行里的信息量其实非常大npx --no是刻意不用 npx 的临时下载能力强制走项目的本地依赖commitlint --edit是让 commitlint 从一个文件中读取提交信息$1是 git 传给 commit-msg 钩子的第一个参数指向一个临时文件。如果你不清楚这三个细节一旦出现“本地能用、别人机器上挂了”的情况排查起来会非常被动。更夸张的是我见过有人手滑把整个 hook 改成commitlint --from HEAD~1 --to HEAD跑当然能跑但校验的根本不是“这一次要提交的内容”而是“上一次 commit 的内容”完全偏离了钩子的设计意图。2. commit-msg 钩子运行的底层机制触发时机、参数与返回值想真正掌控 commit-msg得先把它放进 git 的钩子模型里看。2.1 git hooks 与 Husky 的“代理”逻辑git 原生的 hooks 位于.git/hooks/目录下里面有一堆以.sample结尾的示例脚本包括commit-msg.sample、pre-commit.sample、post-commit.sample等。git 每次执行到对应动作时会去这个目录里找同名可执行文件有就跑没有就跳过。Husky 做的事情就是“代理”。它不修改你的业务脚本而是把 git 的钩子入口统一指向一个由它管理的目录。在新版本里husky install会执行一条关键配置git config core.hooksPath .husky这条命令之后git 不再去.git/hooks/找钩子而是去.husky/找。所以你在仓库根目录看到的那一排.husky/pre-commit、.husky/commit-msg本质上就是让 git 更可控地执行团队约定的一组脚本。这里顺带提一下版本的跃迁。Husky 4 时代钩子配置写在package.json里的husky.hooks下安装依赖时自动注册Husky 9 时代它只认根目录的.husky目录初始化命令也变成了npx husky init钩子里拿 git 参数从$HUSKY_GIT_PARAMS换成了$1。如果你看的旧教程还在教HUSKY_GIT_PARAMS赶紧把手里的配置升级一下。2.2 commit-msg 触发的时机与 COMMIT_EDITMSG 文件git 一次常规提交的钩子顺序大致是pre-commit→prepare-commit-msg→commit-msg→post-commit。pre-commit跑的时候提交信息还不存在用户要么通过-m传了参数要么在编辑器里写完了信息并保存之后 git 才会调用commit-msg。这意味着commit-msg拿到的是“最终版”提交信息。git 会把本次提交的信息写到一个临时文件里路径通常是.git/COMMIT_EDITMSG然后把这个路径作为第一个参数传给 commit-msg 钩子。所以用git commit -m feat: 新增登录时文件里是feat: 新增登录加上一些以#开头的注释用编辑器提交时文件里是模板注释加用户输入内容用git commit -m header -m body时文件里会有两个段落。这也是为什么 commitlint 用--edit而不是把提交信息当字符串传进去——读文件是最可靠的方式。手写校验脚本时同样要遵循这个约定用$1定位文件再从里面解析内容。2.3 退出码决定提交是否成功钩子脚本的本质是一个可执行程序。git 只关心它的退出码返回0提交继续返回非0提交中止。就这么简单。这条规则带来一个非常实用的推论你不需要依赖 commitlint 才能做校验。只要在脚本里能“读文件 判断 退出”任何语言都能写一个 commit-msg 钩子。团队完全可以只用一个几十行的 Shell 脚本而不是引入整个 Node 依赖链。另外记住一点commit-msg的阶段在pre-commit之后。lint-staged 在pre-commit里改了文件然后重新git add这些动作做完提交内容已经确定最后才轮到commit-msg把关信息格式。所以不要试图在pre-commit里校验提交信息那个阶段你根本拿不到完整的提交文本。3. 不装 commitlint手写一个属于自己的 commit-msg 校验脚本先声明我的观点commitlint 很好但它不是唯一解。有些仓库规则非常简单或者团队对提交格式有特殊癖好比如必须带需求单号这时候一套自定义脚本反而更透明、更容易维护。3.1 自定义校验脚本的完整骨架在.husky/commit-msg文件里放下面这段脚本注意 shebang 用sh而不是bash因为 git 在 Windows Git Bash 和各种服务器上的默认解释器并不完全一致POSIX 兼容写法最稳。#!/usr/bin/env sh # .husky/commit-msg # 自定义提交信息校验脚本不依赖 commitlint commit_msg_file$1 # 提取第一行非注释、非空的内容作为提交信息的 header header$(grep -vE ^# $commit_msg_file | grep -vE ^\s*$ | head -n 1 | tr -d \r) # 校验 header 格式type(scope): subject if ! echo $header | grep -Eq ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.\))?: .; then echo echo commit message 不符合团队规范 echo 期望格式: type(scope): subject echo 例如: feat(user): 增加用户注册功能 echo exit 1 fi # 校验 header 长度避免一屏看不完 header_length$(echo $header | awk { print length($0) }) if [ $header_length -gt 100 ]; then echo 提交信息 header 长度超过 100 字符请精简 exit 1 fi # 校验 body 每行长度Git 最佳实践建议 72 字符左右这里放宽到 100 if awk length($0) 100 { print 第 NR 行超过 100 字符: $0; bad1 } END { exit bad } $commit_msg_file; then : else echo 提交信息 body 中存在超过 100 字符的行 exit 1 fi exit 0这段脚本做了三件事提取 header、校验格式、校验行长。删掉注释后大概 30 行挂在.husky/commit-msg下就是一个完整的钩子。3.2 为什么第一步要“剔除注释、取第一行”很多人手写脚本时直接head -n 1 $1然后校验失败。原因很简单当用户用编辑器提交时COMMIT_EDITMSG文件的第一行可能是 git 模板里的注释比如# Please enter the commit message for your changes. Lines starting # with # will be ignored, and an empty message aborts the commit.如果不把#开头的行过滤掉你校验的就变成 git 自己的提示文本而不是用户写的提交主题。我在这个细节上吃过亏后来统一改用“先grep -vE ^#、再grep -vE ^\s*$、最后取第一行”的顺序才把各种编辑器的差异抹平。3.3 规则扩展scope、Breaking Change 与 footer 的校验基础格式跑通以后如果你的团队还需要更细的规则可以在同一套脚本里继续加分支判断。强制 scope让(scope)变成必填项正则改成^(feat|fix|...)\([a-z-]\): .。适合按模块管理的仓库。解析 Breaking Change在正文里识别BREAKING CHANGE:前缀如果存在可以要求 header 必须带!标记避免破坏性变更被悄悄提交。footer 关联单号很多内部项目使用JIRA: PROJ-123或Issue: #456作为 footer可以在脚本里用一行grep -Eq ^(JIRA|Issue):判断是否存在关联信息。自定义 type 清单直接把type-enum从 commitlint 规则里搬出来在正则里列一个自己的白名单。手写脚本有一个天然优势错误提示可以完全贴着自己团队的上下文来写。比如“请检查你的 type 是否在白名单里当前可选feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert”这句话比 commitlint 默认的英文提示更能在半睡半醒的状态下让人看懂。4. 接入 commitlint 的完整配置从装包到规则取舍如果团队规模不小、提交规范想做成行业通用格式直接上 commitlint 更省心。它的规则体系在处理边界情况上比我手写脚本完整得多比如对git revert生成的Revert ...提交、对中文提交信息、对脚注解析都有现成的解析器。下面是一套我在实际项目中反复验证过的接入方式。4.1 装包与初始化项目根目录执行pnpm add -D commitlint/cli commitlint/config-conventional npx husky init npx husky add .husky/commit-msg npx --no -- commitlint --edit $1npx husky add第一次跑会创建.husky/commit-msg文件。注意加号命令里必须用单引号包裹$1如果用双引号Shell 会在当前终端里把$1展开成空写进文件的内容就变成了npx --no -- commitlint --edit钩子运行时拿不到提交信息文件路径。--no参数是很多人容易忽略的点。它的作用是禁止 npx 在本地没有依赖时临时联网安装。加了--no之后如果node_modules/.bin/commitlint不存在命令会直接失败而不是静默下载一个临时版。这保证了“你本地校验通过的规则在别人机器上也一定是同一个版本的 commitlint 在跑”。4.2 配置文件的三种写法与那个经典的 type: module 坑commitlint 默认找commitlint.config.js但对 ES Module 项目来说这个.js文件会被 Node 当作 ESM 解析。如果你在package.json里写了type: module又用module.exports写配置文件跑起来就会报module is not defined。排查链路我走了一次怎么都记不错先看package.json有没有type: module有的话选择二选一——把配置文件改成.cjs后缀内容保持不变// commitlint.config.cjs module.exports { extends: [commitlint/config-conventional], };或者直接把配置文件改成 ESM 语法// commitlint.config.js export default { extends: [commitlint/config-conventional], };我个人更推荐.cjs。原因很现实老项目里的脚本、其他工具链比如一些 CLI可能还在用 CommonJS 读配置文件.cjs的兼容面最广。4.3 规则定制从照搬默认到贴合自身commitlint/config-conventional的默认规则覆盖了社区最主流的 Angular 规范但直接拿过来用往往需要微调。下面这套是我在多个团队落地的基线兼顾了规范性和可操作性// commitlint.config.cjs module.exports { extends: [commitlint/config-conventional], rules: { type-enum: [2, always, [ feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert ]], subject-case: [0], header-max-length: [2, always, 100], body-max-line-length: [2, always, 100], footer-max-line-length: [2, always, 100] } };重点说两个规则。type-enum是提交规范的“宪法”所有 type 的白名单在这里定义。不要照抄大厂那一长串你的团队用不到wip、init、config之类的话白名单越长大家越懒得选最后全都在用chore混过去。五到八个常用 type 足够我把build、ci、revert都放进去了是因为这些确实会偶发出现。subject-case在默认配置里是开的它检查 subject 不应该以某些风格出现。实际问题在于很多输入法或者编辑器会自动把首字母大写用户明明输入的是fix: fix bug编辑器改成fix: Fix bugcommitlint 就报错。这种报错给用户的第一反应是“工具坏了”。我直接把subject-case设成[0]关掉换取的上手体验提升非常明显。4.4--edit $1的语义与手动检测方法.husky/commit-msg里的命令npx --no -- commitlint --edit $1意思是告诉 commitlint去读$1指向的那个文件把内容解析成提交信息并校验。理解这一点后你在本地想手动复现一次校验可以直接对最近一次提交的信息做检查npx --no -- commitlint --edit (git log -1 --format%B)( ... )这种进程替换只有在 bash 里可用做排查用一下没问题。更常见的排查方式是直接看文件内容cat .git/COMMIT_EDITMSG然后手动执行npx --no -- commitlint --edit .git/COMMIT_EDITMSG这样可以快速判断到底是钩子脚本出问题还是 commitlint 规则本身拒绝了内容。5. 踩坑实录merge、amend、CRLF 与 CI 环境的真实翻车现场技术方案看得再多不如在真实环境里被坑一次。下面几个案例是我和不同团队在接入 commit-msg 后实际撞上的每一个都让我对钩子机制的理解更深了一档。5.1 Windows 上正则莫名失败CRLF 的完整排查链路现象描述同事在 Windows 上提交feat: 新增用户中心自定义脚本报“不符合规范”。他觉得很奇怪格式明明是对的中文和英文都试了就是过不去。第一反应是用 commitlint 手动校验报同样的错。然后我把COMMIT_EDITMSG的内容打印出来视觉上完全正常。接下来用sed -n 1l .git/COMMIT_EDITMSG查看不可见字符——这一招非常关键sed的l命令会把一行结尾的不可见字符显示成$。输出结果里第一行末尾有一个\r。根因一下就清楚了Windows 上 git 默认开启了core.autocrlf检出文件时把LF替换成了CRLF。hook 读取COMMIT_EDITMSG时拿到的是带\r的文本而脚本正则里的$锚点匹配的是\n前面的位置残留下来的\r导致整个正则匹配失败。解决方式分两层。外层是规范团队配置在.gitattributes里显式声明提交信息相关的文件保持LF或者让 Windows 同学把core.autocrlf设为input。内层是最稳的自我修复所有手写校验脚本在过滤行时都加一步tr -d \r。上面第三部分给出的脚手架已经包含了这一步凡是没加这一步的 Windows 用户几乎都会踩同一个坑。5.2 merge commit 被误杀一次由 pull 引发的“扑街”某次团队代码合并一位同事执行git pull之后git 自动生成了一个 merge commit提交信息是Merge remote-tracking branch origin/dev into main结果 commit-msg 钩子果断退出码 1把他卡在原地。原因是常规的 commitlint 规则只认type(scope): subject格式Merge ...根本不在 type 白名单里。这个坑的破坏力在于“政治正确”——当你只是想同步代码却被自己的提交规范拦死第一反应往往是骂工具而不是反思规则。长期解法是尽量用git pull --rebase减少自动生成的 merge commit。短期解法是让 commitlint 对 merge 提交放行。具体做法是在配置文件里加一条ignores函数识别以Merge开头的提交直接跳过module.exports { extends: [commitlint/config-conventional], ignores: [(commit) /^Merge\s/.test(commit)], };这个坑提醒我任何校验规则都要想清楚“它拦下的对象里有没有合法用户”。工具的目的是拦错不是拦人。5.3 amend 与 --no-verify钩子不是安全锁很多人不知道git commit --amend会重新触发 commit-msg。如果你第一次提交用了--no-verify逃过校验那么 amend 的时候大概率会被钩子抓住逼你把信息改成合规格式。从流程设计角度看这其实是个不错的兜底。但我也要强调一个现实--no-verify是万能后的门。任何 hook 都能被它跳过husky 不是安全锁它拦的是“不小心”不是“故意”。团队里真正能约束提交规范的只有 code review 和 CI 侧的二次检查。我在 CI 流水线里会额外加一个 step对 PR 的所有提交做范围校验npx --no -- commitlint --from HEAD~$(git rev-list --count HEAD^..origin/main) --to HEAD这样即使本地有人绕过 hook合并前也会被 CI 拦下来。5.4 CI 环境里 hook 静默消失我在一个自动化发布项目里反复碰到一种现象本地提交规范跑得好好的一到 CI 里的机器人提交 commit提交信息就放飞自我。排查后才发现CI 里安装依赖用了npm ci --ignore-scripts这个命令会跳过 npm 的prepare生命周期脚本而 husky 正是在prepare阶段完成core.hooksPath配置的。钩子根本不存在自然也不会有人去校验。对此有三个层面的措施安装依赖时不要全局--ignore-scripts至少让它执行 husky 相关脚本机器人在 CI 里生成的提交在 commit 前显式跑一次校验命令或者干脆接受“CI 自动提交不经过本地钩子”的现实用 GitHub Actions 里现成的 commitlint 检查步骤在 PR 维度兜底。额外提一个细节HUSKY0环境变量可以临时关闭全部 husky 钩子。在那种“只想快速提交一份临时代码不想被任何规则打扰”的场景里它比--no-verify更语义化。但同样地它只能用于本地救急不该成为 CI 的默认配置。6. 团队提交规范落地的最后一公里提交规范能不能真正活下去不取决于规则多严谨而取决于大家“打一条合规提交信息”的成本有多低。我做过几次复盘发现凡是规范推行不下去的团队问题都出在“靠人脑子记格式”上。6.1 用 commitizen 和 cz-customizable 把提交变成交互式问答与其让大家背 type 清单不如把提交命令替换成交互式工具pnpm add -D commitizen cz-customizable在package.json里声明config: { commitizen: { path: cz-customizable } }再放一份.cz-config.js定义中文化的 type 提示module.exports { types: [ { value: feat, name: feat: 新功能 }, { value: fix, name: fix: 修复缺陷 }, { value: docs, name: docs: 文档变更 }, { value: style, name: style: 代码格式调整 }, { value: refactor, name: refactor: 重构 }, { value: perf, name: perf: 性能优化 }, { value: test, name: test: 测试相关 }, { value: chore, name: chore: 构建/工具链杂项 } ], scopes: [user, order, pay, common], allowCustomScopes: true, subjectLimit: 100 };之后团队用它代替原始的git commitcommitlint 仍然照常校验但用户从“背规则”变成了“做选择题”抵触情绪会小很多。6.2 一层更轻量的保障提交模板如果连交互式工具都不想引入还有一个非常轻的落地方式提交模板。在仓库根目录放一个.gitmessage.txttype(scope): subject body footer然后让每个成员执行一次git config --local commit.template .gitmessage.txt之后每次git commit打开编辑器自动带出模板骨架用户只需填空。配合 commit-msg 钩子的校验这基本构成了一个零依赖的规范闭环。6.3 规范提交信息带来的额外回报changelog 可以自动生成提交格式一旦稳定很多工具链会自动受益。standard-version可以直接根据feat、fix、BREAKING CHANGE这些标记自动 bump 版本号并生成 CHANGELOG.md。git bisect查找回归也能靠类型标记快速定位到“引入新功能”的那次提交。我后来在项目里接上 changelog 自动生成以后团队对提交规范的态度从“麻烦”变成了“有回报”这是个很微妙但是很关键的转变。关于 commit-msg 配置如果你之前只把它当成脚手架生成的一行咒语我建议你花十分钟拆开看一遍删掉.husky/commit-msg里的命令改成先cat $1再看它到底长什么样。理解这个文件、理解$1指向的内容你对 git 提交流程的掌控感会明显不一样。我这些年最大的体会是提交信息规范不是一个可以一步到位的工程先让 80% 的提交符合简单规则再慢慢收紧永远比一开始设计一套完美规则然后无人执行要好。