golangci-lint 环境准备核心是 go、golangci-lint 和 go.mod 三者版本对齐；必须确保 Go 版本匹配 go.mod 声明（如均为 1.22.x），否则易 panic 或卡住；Modules 项目须配置 .golangci.yml 并禁用 golint/typecheck，启用 modules-download-mode: readonly，排除生成代码目录。
golangci-lint 本身不依赖 Go 运行时，但必须与项目使用的 Go 工具链版本兼容；环境准备的核心不是“装对工具”，而是确保 go、golangci-lint 和项目 go.mod 三者版本对齐。
Go 版本必须匹配 go.mod 中声明的版本
golangci-lint 的 linter（如 staticcheck、govet）底层调用 Go 的 go/types 和 AST 解析器。若 go.mod 写着 go 1.22，而你本地 go version 是 1.20，golangci-lint run 很可能 panic 报 failed to load program: typechecker error 或卡住超 2 分钟。
- 运行
go version和cat go.mod | grep '^go '，确认两者主次版本一致（如都是 1.22.x） - 多版本共存时，用
go env GOROOT确认当前go命令指向的安装路径，避免 brew / asdf / goenv 切换错位 - CI 中务必显式指定 Go 版本（如 GitHub Actions 用
actions/setup-go@v4），不能只写go install
golangci-lint 安装方式决定 PATH 和权限是否可靠
用 go install 装的二进制默认放在 $(go env GOPATH)/bin，但该目录常不在系统 PATH 中；Homebrew 安装虽方便，但在 macOS Sonoma+ 上可能因 SIP 限制导致权限异常。最稳的方式是下载官方二进制并手动放至 /usr/local/bin：
- 从 GitHub Releases 下载对应平台的
golangci-lint-*.tar.gz（如golangci-lint-1.54.2-darwin-arm64.tar.gz） - 解压后执行
sudo mv golangci-lint /usr/local/bin/ - 验证：
golangci-lint --version和ls -l $(which golangci-lint)确认有可执行权限 - 避免用
curl | sh脚本——它默认装到$(go env GOPATH)/bin，而该路径在 GoLand、VS Code 或 CI 中未必被继承
Modules 项目必须提前配置 .golangci.yml，否则默认启用已弃用 linter
Go Modules 项目没有 .golangci.yml 时，golangci-lint v1.54+ 仍会回退到启用 golint（归档）、typecheck（与 go build 冗余）等冲突项，直接导致检查失败或误报。
- 最小可用配置必须包含
run.modules-download-mode: readonly，否则 lint 过程可能意外修改go.sum -
linters.disable至少要加- golint和- typecheck - 生成代码目录（如
pb.go、mock_*.go）必须用run.skip-dirs或issues.exclude显式排除，否则errcheck会对proto.Unmarshal报错 - 不要依赖 IDE 自动创建配置文件——GoLand 的 “Download” 按钮装的是旧版，且不生成 YAML 结构
真正容易被忽略的点是：golangci-lint 的 run.go 字段（如 run.go: "1.22"）只影响部分 linter 的语义检查行为，它不会覆盖 go.mod 声明的版本，也不能绕过 Go 工具链本身的版本约束。环境准备是否到位，最终就看 golangci-lint run -v 能否在 30 秒内完成且不 panic。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
