.golangci.yml配置生效需严格满足三点：文件名必须为.golangci.yml（点开头、小写yml）、与go.mod同级、YAML语法正确（顶格、空格缩进、无tab）；任一不满足则静默退回到默认linter集。
.golangci.yml 文件名必须严格匹配，不能用 .yaml 或其他变体
golangci-lint 只认 .golangci.yml 这一个文件名（注意是点开头 + yml 小写），不接受 .golangci.yaml、golangci.yml（缺前导点）、.golangci.yml 放在子目录下等情况。一旦拼写或大小写出错，它就完全忽略该文件，退回到默认启用集（仅 govet、errcheck 等约 10 个 linter），且不报任何提示。
验证方式很简单：
-
ls -a | grep golangci确认输出只有.golangci.yml -
file .golangci.yml确保不是二进制或编码错误文件 - 检查是否被 Git 忽略：
git check-ignore -v .golangci.yml
必须与 go.mod 同级，多 module 项目需各自独立配置
配置文件生效的前提是：当前工作目录下存在 go.mod，且 .golangci.yml 与之处于同一目录。golangci-lint 不会向上查找父目录的配置，也不会向下继承到子 module 中。
常见误操作包括：
立即学习“go语言免费学习笔记（深入）”；
- 把
.golangci.yml放在src/或cmd/下，导致根目录运行时失效 - 在 monorepo 中只在根目录放一份配置，但
service/auth/go.mod下的模块完全不读取它 - CI 脚本中执行
cd service/auth && golangci-lint run，却没确认该目录下有.golangci.yml
正确做法是：每个含 go.mod 的子目录都应有一份自己的 .golangci.yml，内容可复用但路径不可省略。
CI 中必须显式指定 --config=.golangci.yml
本地开发时，golangci-lint 会自动发现同级的 .golangci.yml；但在 CI 环境中（尤其是容器或 clean workspace），自动发现经常失败——因为路径切换、权限限制或缓存干扰。
为确保行为一致，所有 CI 脚本里都应强制指定：
golangci-lint run --config=.golangci.yml- 不要依赖
golangci-lint run默认行为 - 如果配置文件不在当前目录，必须写全路径，如
--config=../.golangci.yml（但更推荐复制或链接到当前 module 目录）
缩进与 YAML 语法错误会导致配置静默失效
YAML 对空格极其敏感。哪怕只是 linters 多缩进了一格、linters-settings 写成了 linters 的子项、冒号后少了个空格，整个配置文件都会被跳过——工具不会报错，也不会警告，只会安静地用默认规则跑。
高频出错点：
- 用 Tab 替代空格（YAML 禁止 Tab 缩进）
-
run:和linters:没顶格，而是缩进了 2 或 4 个空格 -
enable:下的列表项缩进不统一（有的 2 空格，有的 4 空格） - 在
linters-settings中误写成linters: settings:这类嵌套结构
建议用 yamllint 或 VS Code 的 YAML 插件预检，或直接运行 golangci-lint run --config=.golangci.yml --debug 查看加载日志中是否有 “Loaded config” 提示。
SA1019 或 unused 错误。 
