pre-commit脚本必须用golangci-lint run --fast,因其强制跳过缓存重建与全量分析,仅检查暂存文件并禁用高开销linter,确保响应在200ms内,避免提交卡顿;否则默认全量扫描会导致几秒延迟,引发用户强制中断提交。

pre-commit 脚本为什么必须用 golangci-lint run --fast
直接跑 golangci-lint run 在提交前会卡住几秒——尤其项目稍大、启用了 staticcheck 或 unused 这类深度分析 linter 时。用户感知就是“git commit 没反应”,下意识会 Ctrl+C 强制提交,等于白配。
--fast 参数强制跳过缓存重建和全量依赖分析,只检查本次暂存区(git add)里的文件,且禁用部分高开销 linter(如 goanalysis 子集)。这不是妥协,而是 pre-commit 场景的合理取舍:你要的是“明显错误拦住提交”,不是“彻底扫描”。
- 别在 pre-commit 里启用
run: modules-download-mode: readonly—— 它会阻塞 module 下载逻辑,而 pre-commit 通常不带网络上下文 - 如果项目用了
replace或本地模块,--fast仍能正确解析路径,但golangci-lint run -v会暴露 module 加载失败细节,调试时可用 - CI 环境该用完整命令,pre-commit 和 CI 的配置应拆开,不要共用同一套
run参数
.golangci.yml 里哪些配置项会影响 pre-commit 响应速度
配置文件不是越细越好,pre-commit 阶段对性能敏感。以下三项改错会导致每次提交多等 1–3 秒:
-
run: timeout设太小(比如30s):小项目没问题,但一旦某次检查触发了gosimple的泛型推导,可能超时中断,报context deadline exceeded却不提示具体 linter -
linters-settings: gocyclo: min-complexity低于10:圈复杂度检查会暴增分析节点数,实测从 120ms 跳到 800ms+ -
linters: enable里保留dupl(代码重复检测):它需要全项目 AST 对比,pre-commit 必须禁用
建议 pre-commit 专用配置节用 if-env: "PRE_COMMIT" 条件加载(需 v1.54+),或干脆维护一个 .golangci.precommit.yml 文件单独引用。
立即学习“go语言免费学习笔记(深入)”;
pre-commit hook 脚本里如何区分 staged 和 unstaged 文件
很多人误以为 golangci-lint run 默认只查 git add 的文件——其实它默认查整个 ./...。必须显式传参限定范围,否则每次提交都扫全量,失去意义。
- 正确做法:用
git diff --cached --name-only --diff-filter=AM | grep '.go$'提取已暂存的 Go 文件,再喂给golangci-lint run --files - 别用
git ls-files -m:它包含未暂存修改,会导致“改了但没add的文件也被检查”,干扰用户预期 - 空暂存区时(比如只改了 README),脚本应直接 exit 0,避免报
no go files to check让人困惑 - Windows 用户注意:
git diff输出路径含反斜杠,需用tr '\\' '/'转义,否则golangci-lint找不到文件
为什么 pre-push 比 pre-commit 更适合跑全量检查
pre-commit 是“最后一道轻量防线”,pre-push 才是真正兜底。两者定位不同,混用反而增加误伤概率。
-
pre-push可安全启用run: skip-dirs: [](清空跳过目录)、打开errcheck+govet全模式,因为它发生在本地网络就绪、用户心理预期是“稍等一下” - 若在
pre-commit里硬塞全量检查,遇到go mod download失败或 proxy 不稳,提交直接失败,开发者第一反应是删 hook,而不是修环境 -
pre-push脚本可加set -o pipefail,确保golangci-lint run | grep -q 'ERROR'这类判断不被管道截断 - Git 2.38+ 支持
pre-push传参(如origin main),可据此跳过某些分支的检查,但 Go 项目极少需要,别过早复杂化
最易被忽略的一点:pre-commit 脚本里调用 golangci-lint 前,务必先 cd $(git rev-parse --show-toplevel)。Git hook 执行路径不可靠,尤其 VS Code 终端或 IDE 内提交时,当前目录可能是子包路径,导致配置文件找不到、module 解析失败。


















