.golangci.yml配置失效最常见原因是文件名或位置错误：必须精确命名且与go.mod同级；多模块项目需各模块独立配置；YAML语法错误（如缩进、冒号空格）会导致静默回退默认集；CI和IDE中必须显式指定--config参数，否则不生效。
配置文件名和位置不匹配导致完全失效
最常见的情况是 .golangci.yml 文件根本没被读到——工具只认这个精确名称，且必须与 go.mod 同级。写成 .golangci.yaml、golangci.yml（缺点）、或放在 src/、cmd/、Git 根目录下，都会静默跳过配置。
验证方式很简单：
- 执行
ls -a确认当前目录同时存在go.mod和.golangci.yml - 运行
golangci-lint help linters | grep -E "^(staticcheck|unused|gosimple)"，如果没输出，说明配置未加载（默认集不含这些） - 多 module 项目（如
api/、shared/）中，每个 module 目录都得有一份独立的.golangci.yml，父目录的配置不会继承
YAML语法与字段层级错位引发静默忽略
YAML 解析失败时，golangci-lint 不报错，而是直接回落到默认启用集（仅 govet、errcheck 等约 10 个）。三个高频出错点：
- 缩进混用 Tab 或空格：必须全用空格，且层级对齐严格
-
linters-settings和run是顶层字段，不是linters的子项；写成嵌套结构会导致整个配置被跳过 - 冒号后少空格（如
enable-all:true→ 正确应为enable-all: true），或复制示例时带入不可见字符（如 Zero Width Space）
建议用 yamllint .golangci.yml 先做基础语法校验（需提前安装 yamllint）。
立即学习“go语言免费学习笔记（深入）”；
exhaustive 检查器在 2.15+ 版本中的配置断裂
升级到 golangci-lint v2.15 后，exhaustive 的配置字段已变更，旧写法仍能解析但不生效：
-
explicit-exhaustive-switch和explicit-exhaustive-map已合并为explicit-exhaustive -
check: map必须改为check: mapliteral，且需显式声明switch、mapliteral或typeswitch -
ignore-enum-members→ 改为ignore-constants，值必须是字符串切片（如["Unknown"]），不能是单个字符串 -
ignore-enum-types→ 改为ignore-types，同样要求切片格式
若本地没报错但 CI 突然爆出大量 exhaustive 问题，先检查 CI 是否启用了 --fast 模式——该模式默认禁用所有 slow 类检查器，而新版 exhaustive 就属于这一类。
CI 和 IDE 中未显式传参导致配置“看似生效实则未用”
golangci-lint 不会自动向上查找配置文件，也不会读取环境变量推导路径。这意味着：
- CI 脚本里只写
golangci-lint run是无效的，必须加--config=.golangci.yml - VS Code 中需确认
"go.lintFlags"包含--config=.golangci.yml，并勾选「使用配置」选项 - GoLand 的 File Watchers 或静态分析器设置里，必须手动填入完整命令，包括
--config参数 - 漏掉
--config就等于没配——它会回落到极简默认集，你看到的“零输出”其实是“根本没跑你想用的检查器”
复杂点在于：同一份配置，在本地 golangci-lint run 可能因当前路径恰好有 go.mod 和 .golangci.yml 而生效，但 CI 中工作目录不同、参数缺失、Go 版本差异（如 GO111MODULE=off）都会让行为不一致。别信“本地能跑就行”，每个执行上下文都要单独验证。
