必须用二进制安装golangci-lint并配置.golangci.yml：禁用go install以防污染module cache；启用errcheck、staticcheck、unused等关键linter，文件名与位置须严格匹配，CI和VS Code中需显式指定配置路径。
golangci-lint 必须用二进制安装，别碰 go install
直接 go install golangci-lint@latest 会污染 module cache，后续 go mod tidy 很可能报 cannot find module providing package。这不是你项目的问题，是 golangci-lint 在 module mode 下被本地 replace 或空 go.mod 路径带偏了。
正确做法只有一条：用官方脚本装二进制
- 运行
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.54.2 - 立刻验证：
golangci-lint --version - 确认
$(go env GOPATH)/bin在$PATH里（macOS 用户重点检查~/.zshrc是否有export PATH="$GOPATH/bin:$PATH"）
.golangci.yml 必须显式启用关键 linter，否则等于没开
不配 .golangci.yml，golangci-lint run 默认只跑 govet（部分子项）、gofmt、goimports，漏掉 errcheck、staticcheck、unused 这些真正揪逻辑错误的检查器。
配置必须满足三个硬条件：
立即学习“go语言免费学习笔记（深入）”；
- 文件名必须是
.golangci.yml（不是.golangci.yaml或golangci.yml） - 必须放在和
go.mod同级目录 - CI 中要显式传参：
golangci-lint run --config=.golangci.yml，它不会自动读
最小有效配置示例（含不可替代性说明）：
linters-settings:
govet:
checks: ["all"] # 不加这行，atomic/bools 类问题全漏
linters:
enable:
- errcheck # 强制处理 error，防 os.Open() // 忽略
- staticcheck # 唯一报 SA1019（弃用 API）、SA4006（无限 for）
- unused # 找未导出函数、无用 import、定义后未读变量
- revive # 替 golint，支持禁用 _ = foo() 这类忽略
disable:
- golint # 官方已归档，规则主观、噪音大VS Code 插件不标红？先查路径链断在哪
Go 插件默认调用 golangci-lint，但常见静默失败场景有三个：
- 插件设置里没勾选「Use config file」，或填的路径是空值 / 相对路径
- IDE 启动时工作目录不是含
go.mod的根目录 → 找不到.golangci.yml或解析错 module path - 插件调用的
golangci-lint版本 revive 规则支持不全，部分告警不触发
快速验证法：在 IDE 打开一个含未使用变量的文件，终端执行
golangci-lint run --config=.golangci.yml --no-config ./path/to/file.go
如果终端能报错但 IDE 不标红，就是插件路径或缓存问题，不是代码没毛病。
CI 中并发和路径配置不当，会导致超时或 OOM
默认并发数 = CPU 核心数，大项目（尤其含大量 _test.go 或 vendor）容易卡死或内存爆掉。这不是 bug，是它真在并行 parse 所有 .go 文件。
实操建议：
- 加
--concurrency=2，CI 环境资源受限时比默认更稳 - 用
--skip-dirs="vendor,third_party"明确跳过非主代码区域（注意分隔符是逗号，不是空格） - 避免
--fast：它跳过unused等耗时检查，掩盖真实技术债务
多 module 项目（monorepo）中，父目录的 .golangci.yml 不会继承到子 module，每个 module 都得单独放一份 —— 这点最容易被忽略。
