golangci-lint 仅识别 module 根目录下的 .golangci.yml（小写 yml），不向上查找；多 module 项目需各子模块独立配置，否则退化为仅启用约 10 个基础 linter 的弱检查模式。
配置文件名和位置必须严格匹配 module 根目录
golangci-lint 不会自动向上查找或继承父级配置，它只认 .golangci.yml（注意是小写 yml，不是 yaml 或 YML），且必须放在 go.mod 所在的目录——也就是你项目的 module 根。多 module 项目（比如 monorepo）中，a/ 和 b/ 各自要有自己的 .golangci.yml，否则它就退回到只跑 govet、errcheck 等约 10 个基础 linter 的“裸奔模式”，大量问题根本不会报。
- 常见错误现象：
golangci-lint run没报错但也不标红，VS Code 里完全没提示，IDE 插件刷新后仍无效 - 真实原因：文件名叫
.golangci.yaml、golangci.yml（缺点）、或放在了src/子目录下 - 实操建议：执行
ls -a | grep golangci确认名字；再用find . -name "go.mod" -exec dirname {} \;定位 module 根
不写配置文件 = 基本等于没装
默认启用的 linter 集合极弱，像 gocyclo（圈复杂度）、goconst（重复字面量）、nilaway（空指针检查）这些关键工具全被关着。你改完配置后，IDE 不会自动 reload，必须手动运行一次 golangci-lint run 触发缓存重建，否则 GoLand 或 VS Code 依然按旧规则跑。
- 容易踩的坑：
skip-dirs: ["vendor"]写了但忘了加run: modules-download-mode: readonly，导致每次 lint 都重 fetch 依赖，超时卡死 - 性能影响：不开
timeout或设得太短（如30s），遇到大项目或 CI 环境慢磁盘，直接报context deadline exceeded - 推荐最小可用配置：
run: timeout: 5m modules-download-mode: readonly linters: enable: - govet - staticcheck - unused - gosimple - ineffassign
CI 中只检查 PR 新增代码，别扫全量
在 GitHub Actions 里直接 golangci-lint run ./ 是最常见反模式：它会扫描 vendor、pb、mocks 等生成代码，不仅慢，还把历史债务全翻出来，PR Review 变成考古现场。
- 正确做法：用
only-new-issues: true+github-token，让 golangci-lint-action 自动 diff 当前 PR 修改的文件范围 - 参数差异：
args: --new-from-rev=origin/main是本地模拟用的，CI 中由 action 内部自动注入，不用手写 - 兼容性注意：该功能要求
golangci-lint-action@v9+且 GitHub token 权限正常（permissions: contents: read必须显式声明）
IDE 插件不生效？先确认路径和配置绑定
GoLand 或 VS Code 的 linter 插件不是“装上就灵”，它默认不读项目级 .golangci.yml，除非你手动指定。而且插件调用的是它自己找的 golangci-lint 二进制，不是你 go install 到 $HOME/go/bin 那个——路径对不上，版本就可能错乱。
立即学习“go语言免费学习笔记（深入）”；
- 实操步骤（GoLand）：
Ctrl+Alt+S→Go | 静态分析器→ 勾选使用配置→ 浏览到项目根目录下的.golangci.yml - VS Code 常见错误：插件设置里
"go.golangci-lint.executablePath"指向了旧版本二进制，或者没重启窗口 - 验证方式：改一行触发
unused的代码，看编辑器是否立刻标黄；不行就打开问题工具窗口，看有没有golangci-lint相关条目
配置真正起效的关键，从来不在“启用了多少个 linter”，而在于你是否让每个环节——命令行、CI、IDE——都明确知道自己该读哪个文件、用哪个路径、作用于哪段代码。漏掉任意一环，就等于白配。
