必须用二进制安装golangci-lint，避免go install污染module cache；需配置.golangci.yml启用errcheck、staticcheck、unused等关键linter，并集成至VS Code和CI，否则默认仅运行保守检查。
golangci-lint 必须用二进制安装，别碰 go install
go install golangci-lint@latest 看起来省事，但实际会污染 module cache、拉取不兼容的依赖版本，甚至导致后续 go mod tidy 报 cannot find module providing package。这不是环境问题，是工具本身在 module mode 下解析路径时被你本地的 replace 或未初始化的本地路径带偏了。
- 用官方脚本装：
curl -sSfL <a href="https://www.php.cn/link/9181303866f74e72f4b4b39ffbd6a330">https://www.php.cn/link/9181303866f74e72f4b4b39ffbd6a330</a> | sh -s -- -b $(go env GOPATH)/bin v1.54.2 - 装完立刻验证：
golangci-lint --version - 检查
$PATH是否含$(go env GOPATH)/bin；macOS 用户重点看~/.zshrc里有没有export PATH="$GOPATH/bin:$PATH"
.golangci.yml 不写就是摆设，默认只开三个保守检查器
不配 .golangci.yml，golangci-lint run 就只跑 govet（部分子项）、gofmt 和 goimports，漏掉 errcheck（忽略 error）、staticcheck（死代码、无效断言）、unused（未用函数）这些真正能救命的检查。
立即学习“go语言免费学习笔记（深入）”；
- 在项目根目录执行
golangci-lint init生成基础文件，再手动改： - 必启 linter 列表：
errcheck、staticcheck、govet、unused、gosimple - 给
govet加checks: ["all"]，否则它连atomic或bools类问题都不报 - 显式禁用
golint—— 官方已归档，规则主观、噪音大
VS Code 里 lint 不亮？大概率是配置没透传或并发卡死
VS Code 的 Go 插件默认调用 golangci-lint，但有两个常见断点：一是插件没读到你的 PATH，二是大项目下默认并发数把内存吃满，直接静默失败。
- 在
.vscode/settings.json里硬写："go.lintTool": "golangci-lint""go.lintFlags": ["--concurrency=2", "--timeout=60s"] - 不要依赖
go.lintOnSave自动修复 ——golangci-lint的--fix只对部分 linter 生效（如gofumpt），errcheck或staticcheck不支持自动修 - 如果编辑器里完全没波浪线，终端进项目根目录手动跑一次
golangci-lint run --out-format=html > report.html，打开 HTML 看是否真没报错，还是插件根本没调起来
CI 中 lint 失败，先看是不是 vendor 或 test 文件拖垮了
GitHub Actions 或 GitLab CI 里 golangci-lint run 超时、OOM 或报一堆第三方包错误，90% 是因为它默认扫描所有 .go 文件，包括 vendor/、third_party/ 和所有 _test.go。
- 在
.golangci.yml里加：skip-dirs: ["vendor", "third_party", "testdata"]skip-files: [".*\.gen\.go"] - CI 命令显式限流：
golangci-lint run --concurrency=2 --timeout=3m - 避免用
--fast：它跳过unused等耗时检查，等于关掉最值钱的几盏灯
复杂点在于：golangci-lint 不是“开了就灵”的黑盒，它严格遵循 go.mod 解析路径，也严格按 .golangci.yml 的层级继承规则合并配置 —— 项目里如果有 ./cmd/ 子模块或 replace 指向未 go mod init 的本地路径，lint 就会当场罢工，而且不报明确错误，只默默跳过。
