把检查左移到提交前:Git Hooks 与 CI 的分工

前面几篇讲的是「把约定写进仓库」,但约定要真正生效,还需要一道道卡口。卡口放在哪里,是个值得想清楚的问题:放得太晚(只在 CI),问题反馈慢、修复成本高;放得太早(什么都在本地跑),又会被绕过、拖慢节奏。

AI 编码助手让这个问题更突出:它生成代码快、改动多,如果反馈环太长,错误会被成批带进仓库;如果全靠本地自觉,AI 也会「抄近路」。

本文讲检查左移:把检查从「事后」移到「写代码 / 提交时」,以及本地 Git Hooks 与 CI 之间怎么分工。本文承接上下文篇,下一篇是依赖治理。完整导航见文末。

一、什么是「检查左移」

「检查左移」(shift left)指的是:把验证从「发布前 / 合并后」前移到「编码时 / 提交前」。它的依据并不复杂——反馈环越短,修复成本越低:一个在保存时就能发现的格式问题,改起来只要一秒;等到 CI 红了在改,要重新拉分支、定位、重跑;等到线上出事,代价更是数量级放大。

一条代码从写到合入,会经过几道可选的验证点:

  • 编辑器 / 保存时:格式化、lint 提示,秒级反馈;
  • Git Hooks(提交前):提交动作触发的本地检查,秒级到十秒级;
  • CI(推送 / PR 时):全量检查,分钟级。

「左移」不是把所有检查都堆到最早的那一层,而是让每类检查出现在它该在的层——这正是本文要讲清楚的分工。

二、三层防线:各管各的

层次时机速度权威性谁能绕过适合做什么
编辑器保存文件秒级无(提示)任何人即时格式化、实时 lint 提示
Git Hooksgit commit秒级~十秒本地本人(--no-verify)暂存文件 lint、格式化、提交信息规范
CI推送 / PR分钟级团队权威几乎不能全量 lint、测试、构建、类型检查、安全扫描

三层是递进关系:越靠前越快、越个性化、越可被绕过;越靠后越慢、越共享、越权威。理想状态是——靠前的层尽量多「拦下」问题,靠后的层负责「兜底」。

三、为什么 Hooks 不能当唯一防线

本地 hooks 很香,但它有三个天然局限,决定了它只能是「效率层」,不是「安全层」:

  1. 可以被显式跳过。 Git 官方文档写明:pre-commit 钩子「can be bypassed with the --no-verify option」。也就是说,任何人都可以在提交时加一个参数绕开它。
  2. 不随仓库分发。 hooks 默认放在 .git/hooks/,而 .git 目录不会被 git clone 带走;新成员克隆下来是没有这些钩子的。所以需要 husky / lefthook 这类工具,把钩子配置写进仓库、在 npm install 或 lefthook install 时写入 .git/hooks/。
  3. 只存在于个人机器。 钩子是本地脚本,可以被删除、被改动,每个人的环境也不一致(装没装依赖、版本对不对)。

把规范完全寄托在 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 侧兜底。

六、落地清单

  1. 先把 CI 立起来:全量 lint + test + build,作为权威卡口。
  2. hooks 只做秒级检查:格式化、暂存文件 lint、提交信息校验。
  3. 两边共用同一份配置,改动规则时一起 review。
  4. 用 husky / lefthook 管理钩子,用 lint-staged 或 {staged_files} 限定到本次改动。
  5. 明确「强制」归 CI / 服务端,hooks 只负责「更早发现问题」。
  6. 定期确认 hooks 仍被执行(看提交日志、或在 CI 里做一次「本地检查是否被跳过」的抽查)。

参考链接

系列文章


把检查左移到提交前:Git Hooks 与 CI 的分工
https://bubao.github.io/posts/8d3b7e1f.html
作者
一念
发布于
2026年11月21日
许可协议