golangci-lint需通过Git pre-commit hook手动集成，最可靠方式是编写轻量shell脚本：仅检查暂存的Go文件、显式切换至项目根目录、捕获输出、禁用耗时检查并自动化部署。
golangci-lint 本身不提供 pre-commit 集成能力，必须靠 Git hook 脚本或 pre-commit 框架手动桥接；直接把 golangci-lint run 塞进 .git/hooks/pre-commit 是最轻量、最可控的方式，比用第三方 pre-commit 框架更少隐性依赖和兼容问题。
怎么写一个可靠的 pre-commit 脚本
Git 的 pre-commit hook 是 shell 脚本，执行失败（exit code ≠ 0）会中止提交。关键不是“能不能跑”，而是“报错时是否明确、是否可中断、是否不影响非 Go 文件”。
- 脚本必须放在项目根目录的
.git/hooks/pre-commit，且需可执行：chmod +x .git/hooks/pre-commit - 只检查被暂存的 Go 文件，避免全量扫描拖慢提交：
git diff --cached --name-only --diff-filter=ACM | grep '\.go$' - 若无 Go 文件变更，直接 exit 0，不触发
golangci-lint - 显式指定工作目录为项目根，防止在子目录下执行时路径错乱：
cd "$(git rev-parse --show-toplevel)" - 捕获
golangci-lint输出并 echo 给用户看，否则错误静默失败，开发者不知道哪错了
为什么别急着用 pre-commit framework
Python 的 pre-commit 框架虽支持多语言 hook，但对 Go 生态有明显水土不服：
-
golangci-lint依赖 Go 环境和GOBIN或$PATH中的二进制，而pre-commit默认用隔离环境运行，容易找不到命令 - 它的
language: golang不处理模块版本，go install可能拉取非预期版本，导致团队本地检查结果不一致 - 每次提交都重装/校验 hook，比纯 shell 脚本多几百毫秒开销，频繁 commit 时感知明显
- 错误堆栈常混入框架自身日志，掩盖真实
golangci-lint报错行号
golangci-lint run 在 hook 里怎么调才不翻车
常见失败不是 lint 本身挂了，而是执行上下文不对：
立即学习“go语言免费学习笔记（深入）”；
- 别用
golangci-lint run ./...——./会扫描整个目录，包括vendor/、testdata/，既慢又可能误报；改用golangci-lint run --no-config --fast $(git diff...)，只扫暂存区里的 .go 文件 - 加
--fast参数跳过缓存重建，hook 场景下没必要等完整分析 - 禁用耗时 linter：在 hook 脚本里临时覆盖配置，比如
golangci-lint run --disable-all --enable gofmt --enable govet --enable errcheck，保证 sub-500ms 完成 - 若项目有
.golangci.yml，确保它没启用run.skip-dirs以外的路径过滤逻辑，否则 hook 和 CI 行为可能不一致
怎么让团队新人一键启用
没人会手动去 .git/hooks/ 放脚本，得自动化：
- 写一个
init.sh，内容是cp scripts/pre-commit .git/hooks/ && chmod +x .git/hooks/pre-commit - 在 README 里强调：“首次 clone 后请运行
./init.sh”，而不是“请手动配置 hook” - 把
pre-commit脚本放进版本库（如.githooks/pre-commit），避免.git/hooks/被 git 忽略导致丢失 - 可选：在
go.mod的//go:build ignore注释块里加一行提示，// 注意：提交前需运行 ./init.sh 启用 pre-commit 检查，IDE 打开文件时也能看到
真正难的不是让 golangci-lint 跑起来，而是让它在每个开发者的终端里行为一致、失败时有明确提示、不因路径/环境/Go 版本差异导致“别人能过我过不了”。shell hook 看似原始，反而最容易控制这些变量。
