golangci-lint 配置常见陷阱包括:enable/disable 互斥导致启用列表异常;顶层字段缩进错误致配置静默失效;exhaustive 配置键名变更后旧配置被忽略;CI 中未显式指定 --config 参数则不加载配置;多 module 项目需各目录独立配置。

enable 和 disable 不能共存
golangci-lint 的 linters.enable 和 linters.disable 是互斥策略,配置里同时出现会导致行为不可预测——工具不会报错,但实际启用列表可能为空或回退到默认集。常见现象是加了 disable: ["golint"] 后,staticcheck 也没了,因为 enable 没写全,而 disable 又把默认启用项也干掉了。
推荐做法只选一种:日常用 enable 显式声明,比如:
linters:
enable:
- govet
- errcheck
- staticcheck
- unused
- gosimple
这样逻辑清晰、可维护性强,也不会被未来版本的默认启用集变更影响。
顶层字段缩进错位导致整个配置失效
run、linters、linters-settings 必须是 YAML 顶层字段,彼此平级、顶格书写。一旦把 linters-settings 缩进成 linters 的子项,或者多空了一格,YAML 解析器会静默失败,golangci-lint 就当配置不存在,直接回落到极简默认集(仅 govet、errcheck 等约 10 个)。
检查要点:
- 用
yamllint .golangci.yml验证基础语法(需提前安装) - 确认所有顶层字段前无空格,冒号后有且仅有一个空格
- 禁止使用 Tab,全部用空格缩进
- 避免从网页复制示例,可能带入全角空格或 Zero Width Space
exhaustive 配置字段变更引发静默失效
升级到 golangci-lint ≥2.15 后,exhaustive 的配置键名已变:explicit-exhaustive-switch 和 explicit-exhaustive-map 合并为 explicit-exhaustive;check: map 必须改为 check: mapliteral;ignore-enum-members 改为 ignore-constants,且值必须是字符串切片(如 ["Unknown"]),不是单个字符串。
旧配置不会报错,但会被完全忽略——你改了 ignore-enum-members 却发现枚举漏分支还是被报出来,就是这个原因。正确写法示例:
linters-settings:
exhaustive:
explicit-exhaustive: true
check: mapliteral
ignore-constants: ["Unknown", "Unused"]
CI 中不传 --config 参数等于没配
golangci-lint 不会自动向上查找或继承配置,哪怕 .golangci.yml 文件存在且位置正确,CI 脚本里只写 golangci-lint run,它也不会加载。结果就是:本地跑出一堆 SA 规则告警,CI 却安静退出、零输出。
必须显式指定:
- CI 脚本中:用
golangci-lint run --config=.golangci.yml - VS Code:在设置里确认
"go.lintFlags"包含--config=.golangci.yml,且勾选「使用配置」 - GoLand:File Watchers 命令栏必须填完整路径 +
--config参数
最容易被忽略的是:多 module 项目中,每个 module 目录都得有自己的一份 .golangci.yml,根目录的配置不会向下传递——这不是 bug,是设计如此。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











