配置不生效主因是文件未被读取而非规则错误；需确认.golangci.yml存在且路径正确、YAML语法无误、IDE/CI显式指定--config参数，并注意多module项目配置位置及新版字段变更。
配置不生效，90% 是文件没被读到，而不是写错了规则。 golangci-lint 不会报“配置加载失败”，它只会安静地退回到极简默认集（govet、errcheck 等约 10 个），你看到的“没报错”其实是“根本没跑你想用的检查器”。
确认 .golangci.yml 是否被识别
先验证工具是否真的加载了你的配置：
- 运行
golangci-lint help linters，如果输出里只有govet、errcheck、deadcode这类基础项，而没有staticcheck、unused、gosimple，说明配置未生效 - 执行
ls -a，确认当前目录同时存在go.mod和.golangci.yml（注意：是点开头 +yml小写，不是.yaml、golangci.yml或带 BOM 的文件） - 多 module 项目中，
.golangci.yml必须放在每个 module 的根目录下，父目录的配置不会向下继承
检查 YAML 语法与字段层级
YAML 解析失败时，golangci-lint 不报错，而是直接跳过整个配置文件：
-
linters-settings和run必须是顶层字段，顶格书写；写成linters.linters-settings或缩进错位会导致静默失效 - 必须全用空格缩进，混入 Tab 会被 YAML 解析器拒绝（可用
yamllint .golangci.yml验证） -
linters.enable是列表，每项前必须是-（短横 + 空格），不能是-紧跟字母，也不能漏空格 - 避免复制网上配置时带入不可见字符（如 Zero Width Space、全角空格）
CI 和 IDE 中必须显式传参 --config
golangci-lint 不会自动向上查找配置文件，也不会读取环境变量推导路径：
立即学习“go语言免费学习笔记（深入）”；
- CI 脚本中不能只写
golangci-lint run，必须明确指定golangci-lint run --config=.golangci.yml - VS Code：在设置中确认
"go.lintFlags"包含--config=.golangci.yml，且勾选「使用配置」 - GoLand：Settings → Go → Static Analysis → 勾选「使用配置」并填入完整路径；否则表格里手动勾选的 linter 会被忽略
- IDE 中即使路径正确，若未启用 Go Linter 插件或未指定可执行文件路径，编辑器内也不会显示波浪线
升级后 exhaustive 或 staticcheck 不工作？查字段变更和 --fast 模式
golangci-lint 2.15+ 对部分 linter 的配置字段做了不兼容调整，旧写法会被静默忽略：
-
explicit-exhaustive-switch和explicit-exhaustive-map已合并为explicit-exhaustive，且check值必须是switch、mapliteral或typeswitch，不再支持true或map -
ignore-enum-members→ 改为ignore-constants，值必须是字符串切片（如["Unknown"]），不能是单个字符串 - CI 中若用了
--fast模式，exhaustive会被跳过（它被划入 slow 分组），本地没加该参数就可能表现不一致 - 检查
go version和GO111MODULE=on，低版本 Go（staticcheck 缺少类型信息，误判为“未使用”或漏报弃用
最常被忽略的一点：配置文件存在 ≠ 被加载。它对路径、命名、缩进、字段层级、命令参数四者都敏感，任一出错即回落默认行为——而这个“默认行为”恰恰是最容易让人误以为“配置生效了”的假象。
