把检查左移到提交前:Git Hooks 与 CI 的分工
前面几篇讲的是「把约定写进仓库」,但约定要真正生效,还需要一道道卡口。卡口放在哪里,是个值得想清楚的问题:放得太晚(只在 CI),问题反馈慢、修复成本高;放得太早(什么都在本地跑),又会被绕过、拖慢节奏。
AI 编码助手让这个问题更突出:它生成代码快、改动多,如果反馈环太长,错误会被成批带进仓库;如果全靠本地自觉,AI 也会「抄近路」。
本文讲检查左移:把检查从「事后」移到「写代码 / 提交时」,以及本地 Git Hooks 与 CI 之间怎么分工。本文承接上下文篇,下一篇是依赖治理。完整导航见文末。
一、什么是「检查左移」
「检查左移」(shift left)指的是:把验证从「发布前 / 合并后」前移到「编码时 / 提交前」。它的依据并不复杂——反馈环越短,修复成本越低:一个在保存时就能发现的格式问题,改起来只要一秒;等到 CI 红了在改,要重新拉分支、定位、重跑;等到线上出事,代价更是数量级放大。
一条代码从写到合入,会经过几道可选的验证点:
- 编辑器 / 保存时:格式化、lint 提示,秒级反馈;
- Git Hooks(提交前):提交动作触发的本地检查,秒级到十秒级;
- CI(推送 / PR 时):全量检查,分钟级。
「左移」不是把所有检查都堆到最早的那一层,而是让每类检查出现在它该在的层——这正是本文要讲清楚的分工。
二、三层防线:各管各的
| 层次 | 时机 | 速度 | 权威性 | 谁能绕过 | 适合做什么 |
|---|---|---|---|---|---|
| 编辑器 | 保存文件 | 秒级 | 无(提示) | 任何人 | 即时格式化、实时 lint 提示 |
| Git Hooks | git commit | 秒级~十秒 | 本地 | 本人(--no-verify) | 暂存文件 lint、格式化、提交信息规范 |
| CI | 推送 / PR | 分钟级 | 团队权威 | 几乎不能 | 全量 lint、测试、构建、类型检查、安全扫描 |
三层是递进关系:越靠前越快、越个性化、越可被绕过;越靠后越慢、越共享、越权威。理想状态是——靠前的层尽量多「拦下」问题,靠后的层负责「兜底」。
三、为什么 Hooks 不能当唯一防线
本地 hooks 很香,但它有三个天然局限,决定了它只能是「效率层」,不是「安全层」:
- 可以被显式跳过。 Git 官方文档写明:
pre-commit钩子「can be bypassed with the--no-verifyoption」。也就是说,任何人都可以在提交时加一个参数绕开它。 - 不随仓库分发。 hooks 默认放在
.git/hooks/,而.git目录不会被git clone带走;新成员克隆下来是没有这些钩子的。所以需要 husky / lefthook 这类工具,把钩子配置写进仓库、在npm install或lefthook install时写入.git/hooks/。 - 只存在于个人机器。 钩子是本地脚本,可以被删除、被改动,每个人的环境也不一致(装没装依赖、版本对不对)。
把规范完全寄托在 hooks 上,等于把团队约定交给「每个人的自觉」——这正是系列总述里说的「文档式约定」:请求,而非约束。
四、分工原则:快检查归 Hooks,全量归 CI,规则同源
1. 快检查归 hooks。 只把「秒级、只涉及本次改动」的检查放进 pre-commit:格式化、对暂存文件跑 lint、校验提交信息。husky / lefthook 都支持只处理暂存文件(lefthook 的 {staged_files}、lint-staged 的同名机制),避免全量扫描把提交拖慢。
2. 全量归 CI。 全量 lint、测试、构建、类型检查、安全与许可证扫描,都放在 CI。它慢,但权威、共享、不可被个人绕过。
3. 规则同源。 hooks 和 CI 必须读同一份配置(eslint.config.js、.golangci.yml、.clang-format 等)。各跑各的规则,就会出现「本地过了、CI 挂了」的经典割裂。
4. 增量与全量配合。 hooks 只做增量(本次暂存的文件);CI 既跑全量、也可跑增量(如只检查相对基线的改动)。CI 是「事实标准」,hooks 是「加速器」。
一句话:hooks 负责「提前发现」,CI 负责「保证底线」。
五、几个常见反模式
- 把整套测试放进 pre-commit。 提交一次要几分钟,结果只有两个:大家开始
--no-verify,或者干脆不提交。检查左移不等于检查前移一切。 - 把安全红线放在 hooks。 钩子可被跳过、可被删,任何「必须挡住」的东西都必须放在 CI / 服务端。
- 本地与 CI 规则不一致。 要么本地松、CI 严(本地过 CI 挂),要么相反(本地挂 CI 过)。根治办法是同一份配置文件驱动两边。
- 在 hooks 里跑依赖完整环境的任务。 比如需要先构建再跑集成测试——本地环境不一定具备,容易产生「在我机器上是好的」。
- 装了 hooks 却从不执行。 没有
prepare/install步骤、或新成员不知道要装,hooks 就形同虚设。把它写进 README 的上手清单,并在 CI 侧兜底。
六、落地清单
- 先把 CI 立起来:全量
lint+test+build,作为权威卡口。 - hooks 只做秒级检查:格式化、暂存文件 lint、提交信息校验。
- 两边共用同一份配置,改动规则时一起 review。
- 用 husky / lefthook 管理钩子,用 lint-staged 或
{staged_files}限定到本次改动。 - 明确「强制」归 CI / 服务端,hooks 只负责「更早发现问题」。
- 定期确认 hooks 仍被执行(看提交日志、或在 CI 里做一次「本地检查是否被跳过」的抽查)。
参考链接
- Git 官方文档:githooks(含
pre-commit与--no-verify) - Git 官方文档:git-commit
- husky · lefthook · lint-staged
系列文章
- 总述:代码规范工具到底在解决什么问题
- 环境配置:Node.js · Go · C/C++
- 协作机制:给 AI 编码助手补上项目上下文 · 把检查左移到提交前 · 依赖治理 · 命令收口
- 一致性与评审:本地开发与 CI 的一致性 · AI 生成代码的评审清单
