pre-commit钩子中golangci-lint不阻断提交的根本原因是其默认不设非零退出码,需加--fix自动修复或|| exit 1强制失败,并配合git add -u暂存修改,且原生钩子与pre-commit框架不可混用。

pre-commit 钩子里直接调用 golangci-lint 会失败
常见现象是:钩子脚本执行完没报错,但代码有 lint 问题仍能提交成功。根本原因不是 golangci-lint 没运行,而是它默认只输出问题,不设置非零退出码——Git 把它当“成功”处理了。
必须显式启用 --fix 或强制失败模式:
- 加
--fix自动修复可修问题(如格式、未用变量),但注意它会改文件,后续必须git add -u - 加
--out-format=github-actions或简单粗暴用|| exit 1确保出错就中断提交 - 别漏掉
--fast:跳过耗时检查(如govet的 data race),避免钩子卡住 - 限定检查范围:
golangci-lint run --fix --fast --new-from-rev=HEAD~1只扫本次暂存区改动,提速且不误伤老代码
原生 .git/hooks/pre-commit 和 pre-commit 框架不能混用
如果你在项目里同时有 .git/hooks/pre-commit 文件和 .pre-commit-config.yaml,Git 只认前者;pre-commit 框架的命令(如 pre-commit install)根本不会生效。
选一个路径并清理干净:
立即学习“go语言免费学习笔记(深入)”;
- 用原生钩子:删掉
.pre-commit-config.yaml和.pre-commit-hooks.yaml,确保.git/hooks/pre-commit有#!/bin/sh开头、chmod +x权限 - 用
pre-commit框架:删掉整个.git/hooks/下的手写钩子,用pre-commit install注册,配repo: https://github.com/golangci/golangci-lint - 二者都装了?先跑
pre-commit uninstall再决定走哪条路
golangci-lint 找不到配置或模块路径
本地跑 golangci-lint run 正常,但 pre-commit 里报 failed to load config 或 cannot find package,基本是工作目录或环境变量错位。
关键点:
- 原生钩子里加
cd "$(git rev-parse --show-toplevel)"切到项目根,否则.golangci.yml可能读不到 - goimports 类工具依赖
GOPATH和GOPROXY,钩子里补上:export GOPATH=$HOME/go GOPROXY=https://proxy.golang.org,direct - 如果项目用 Go 1.21+ 的 workspace 模式,
golangci-lint默认不识别,得加--modules-download-mode=readonly参数 - CI 里没问题、本地 pre-commit 报错?大概率是 shell 启动方式不同(如 macOS 的 Terminal 用 zsh,Git 钩子走 sh),统一用
#!/usr/bin/env bash开头更稳
格式化后文件没被暂存,提交被拒绝
这是最隐蔽的坑:golangci-lint --fix 改了代码,但 Git 不知道这些变更该进这次提交——它只看暂存区。钩子一结束,Git 发现工作区有未暂存修改,直接拒绝提交,还可能报 please commit your changes or stash them。
必须在钩子末尾加同步暂存逻辑:
-
git add -u:只把已跟踪文件的修改加进暂存区(安全,不碰新文件) - 如果用了
--fix且允许新增文件,再补一句git add -N - 加个判断:只有
git status --porcelain有输出时才git add,避免无意义操作 - 别在钩子里调
git commit—— 会造成递归触发,死循环
复杂点在于:一旦 --fix 修改了文件,就得重新 lint 一遍确认没新问题,否则可能漏检。简单项目可接受单次 fix;严谨场景建议钩子里只做检查(不带 --fix),把修复留给开发者手动跑 golangci-lint --fix。


















