自定义规则集需通过 enable 显式声明、disable 排除及 linters-settings 调参三者组合实现;enable 与 disable 语义互斥,配置中不可共存;推荐始终使用 enable 以确保可预测性、避免隐式继承默认集。

直接说结论:自定义规则集不是靠“写新规则”,而是靠 enable 显式声明 + disable 排除 + linters-settings 调参,三者组合才能真正落地你想要的检查边界。
为什么 enable 和 disable 不能同时用
golangci-lint 的配置解析器会直接报错退出:error: cannot specify both 'enable' and 'disable' sections。这不是设计疏漏,而是语义冲突——enable 是白名单模式(只运行列出的 linter),disable 是黑名单模式(在默认集合里关掉几个)。两者逻辑互斥。
日常推荐始终用 enable,理由很实际:
- 避免隐式继承默认启用集(当前版本默认启用了约 50+ linter,其中部分已过时或重叠)
- CI 环境中行为更可预测,不因 golangci-lint 升级自动引入新 linter 导致构建失败
- 团队新人能一眼看清“我们到底在查什么”,而不是反向推导“哪些被关了”
示例配置节选:
linters:
enable:
- gofmt
- govet
- errcheck
- staticcheck
- unused
linters-settings 怎么调才不踩坑
这个 section 不是“可选装饰”,而是控制规则敏感度的核心开关。很多团队开了 staticcheck 却抱怨“报太多”,其实只是没调阈值。
常见参数差异和影响:
-
gocyclo.min-complexity: 15:圈复杂度告警下限,设太低(如 5)会导致大量 trivial 函数误报;设太高(如 30)可能漏掉真实高风险函数 -
funlen.lines: 60:函数行数限制,注意它和statements是“或”关系,只要任一超限就告警 -
gocritic.enabled-checks:必须显式列出要开的子规则,比如"rangeValCopy"防止切片遍历时复制大对象,不列进去就等于没开 -
govet.enable-all: true后,仍需disable: ["fieldalignment"]手动关掉对齐警告——因为该检查在某些结构体场景下会产生大量噪音
CI 中跑得慢?关键不在 linter 数量,而在路径和缓存
本地 golangci-lint run 秒出结果,CI 却卡 2 分钟?大概率是没跳过无关目录,也未启用缓存。
实操建议:
- 强制跳过 vendor/testdata:在 CI 命令中加
--skip-dirs=vendor,testdata,比在.golangci.yml的run.skip-dirs更可靠(避免配置文件被忽略) - 启用共享缓存:设置环境变量
GOLANGCI_LINT_CACHE=/tmp/golangci-cache,并确保该路径在 job 间可复用(如 GitHub Actions 的actions/cache) - 别在 CI 主流程用
--fast:它会跳过unused等耗时 linter,但这类检查恰恰能发现未引用的常量/函数,属于关键质量门禁 - 验证 Go module 状态:CI 中先跑
go build ./...成功,再跑 lint;否则undefined: xxx报错基本是go.mod解析失败,不是规则问题
自定义 analyzer 不是 YAML 配置能搞定的事
想强制所有 handler 必须带 context.Context,或禁止结构体字段用 time.Time?这些业务语义规则无法通过 .golangci.yml 实现。
真正路径是写 Go 代码:
- 用
go/analysis包实现analysis.Analyzer,核心是Run(*analysis.Pass)函数 - 导出变量名必须叫
Analyzers(复数),类型为[]*analysis.Analyzer,且每个 analyzer 的Doc字段不能为空字符串 - 集成进 golangci-lint 需编译成插件二进制,并在配置中用
plugins字段声明路径,不是加进linters-settings
这一步绕不开 AST 遍历和类型系统理解,配置文件只负责“加载”,不负责“定义”。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











