用 Git 钩子把低级错误拦在提交之前：一次 pre-commit 实战

上周代码评审时，同事提交的代码里又出现了行尾空格、调试用的 console.log 和一个没通过格式化的长函数。问题都不大，但每次都要在评审里反复提醒，时间就这样一点点被磨掉。后来我们决定把这些低级错误拦在提交之前，用的就是 Git 钩子。

一、钩子到底是什么
Git 钩子是藏在 .git/hooks 目录下的一组脚本，名字决定了触发时机。pre-commit 在提交前运行，commit-msg 在提交信息写好后运行，pre-push 在推送前运行。钩子返回非零值，提交就会被挡住；返回零，流程继续。理解这一点就够了，不需要先背全所有钩子。

二、一次真实的教训
有一次我把本地调试用的临时日志带进了提交，CI 跑了十几分钟才在测试阶段报错。那次之后我写了第一个 pre-commit 钩子：先跑格式化检查，再扫一遍调试关键字。规则很简单，发现 console.log、debugger 或者临时打印标记，就直接退出并提示文件名和行号。钩子拦下提交的那一刻，比 CI 报错早了十几分钟，也比评审时被指出体面得多。

三、动手搭一个能用的 pre-commit
团队里更推荐用 pre-commit 框架，而不是每个人手写 shell 脚本。先在仓库根目录建一个 .pre-commit-config.yaml，声明要用的检查：trailing-whitespace 去掉行尾空格，end-of-file-fixer 保证文件以空行结尾，check-yaml 校验 YAML 语法。再按语言加上对应的格式化工具，前端项目加 prettier，后端 Python 项目加 ruff。装好之后跑一次 pre-commit install，钩子就装进了本地仓库；再跑一次 pre-commit run --all-files，对历史文件做一次全面检查，避免第一次提交就被一堆旧问题拦住。

这里有个细节容易踩坑：钩子只在本地生效，新同事克隆仓库后如果没有执行 install，钩子等于不存在。所以我们把 install 写进了项目 README 的上手步骤，也在新人入职清单里加了一行。另一个细节是不要把钩子写得太重，检查控制在几秒内完成，太慢的检查（比如全量测试）应该放到 CI 里，而不是 pre-commit 里。

四、给团队定三条规矩
第一，只拦客观错误，不拦主观风格。格式、空格、调试残留可以自动判断，就交给钩子；命名好不好、抽象合不合理，留给人来评审。第二，钩子报错信息要说清楚怎么修，而不是只抛一个退出码。提示里写明文件名、行号和修复命令，新人也能自己解决。第三，定期复盘钩子的拦截记录。如果某个规则一周拦了几十次，说明不是大家粗心，而是流程或模板有问题，应该从源头上去修。

钩子不是为了为难写代码的人，而是把重复的提醒交给机器，让评审回到真正值得讨论的地方：设计是否合理，边界是否想清楚，改动会不会影响别人。先把提交前的几分钟用好，合并请求里的低级错误自然会少下来。