golangci-lint仅识别严格匹配的.golangci.yml(点开头、全小写、yml后缀),且必须与go.mod同级;多module项目需各模块独立配置,缩进错误或字段名变更均静默失效。

配置文件名和路径对不上,根本不会加载
golangci-lint 只认 .golangci.yml(注意是点开头、全小写、后缀是 yml),其他任何变体都会被完全忽略:.golangci.yaml、golangci.yml、.golangci.yml.bak 全都不行。它也不会向上查找父目录——必须和 go.mod 在同一级目录。多 module 项目中,每个子模块目录都得单独放一份,根目录的配置不会继承下去。
常见错误现象:golangci-lint run 安静退出、零输出,但 CI 却报一堆 SA1019 或 unused;本地改了配置却没反应。
- 先执行
ls -a | grep golangci,确认当前目录下确实存在且拼写完全匹配.golangci.yml - 再运行
go list -m,确认当前目录有合法go.mod并能解析出模块名 - CI 脚本里别省事,必须显式传参:
golangci-lint run --config=.golangci.yml
YAML语法或缩进错一个空格,整个配置静默失效
golangci-lint 不会报 YAML 解析错误,而是直接跳过配置文件,回落到极简默认集(仅 govet、errcheck 等约 10 个)。所有顶层字段(run、linters、linters-settings、output)必须顶格、彼此平级,缩进只能用空格,不能用 Tab。
典型误配:
-
linters-settings被缩进到linters下面,变成子项 -
linters.enable列表项前漏了-后的空格,或用了全角空格/Zero Width Space - 冒号后面少空格,比如
enable-all:true(正确应为enable-all: true)
建议用 yamllint .golangci.yml 验证基础语法(需提前安装),比靠肉眼更可靠。
CI 或 IDE 里不生效,其实是没指定配置路径
golangci-lint 不会自动发现配置文件,也不读环境变量推导路径。在 CI 和主流 IDE 中,必须显式指定 --config 参数,否则它根本不知道你写了啥。
- GitHub Actions:
args: --config .golangci.yml(注意路径是相对工作目录的) - VS Code:检查设置中
go.lintFlags是否包含--config=.golangci.yml,并确认勾选了「使用配置」 - GoLand:File Watchers 的命令行里,必须填完整命令,例如
golangci-lint run --config=$ProjectFileDir$/.golangci.yml
漏掉 --config 就等于没配——你看到的“没报错”其实是“根本没跑你想用的检查器”。
升级后配置字段变更,旧写法被忽略却不报错
比如从 golangci-lint 2.14 升到 2.15 后,exhaustive 的配置结构变了:explicit-exhaustive-switch 和 explicit-exhaustive-map 已合并为 explicit-exhaustive;check: map 必须改为 check: mapliteral;ignore-enum-members 改成 ignore-constants,且值必须是字符串切片(如 ["Unknown"])。
旧配置不会报错,但会被静默跳过——你改了配置却看不到效果,不是工具坏了,是字段名已失效。
- 检查
linters-settings.exhaustive下是否用了已废弃的键名 - 确认
check字段明确写了switch、mapliteral或typeswitch,而不是笼统的true - CI 中若加了
--fast,新版exhaustive默认被禁用,需去掉该 flag 或显式启用
最麻烦的是:这些失效点没有提示,只有对比文档逐项核对才能发现。配置越复杂,越容易卡在这种细节上。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











