Go Modules 项目必须显式配置.golangci.yml,否则回退至启用golint、typecheck等已弃用linter的默认配置,易致误报、panic或CI卡死;文件名须为.golangci.yml、与go.mod同级、缩进仅用空格、顶层字段平级,且CI中须显式指定--config参数。

Go Modules 项目不写 .golangci.yml,等于没配 golangci-lint —— 它会退回到启用 golint、typecheck 等已弃用或冗余检查器的默认配置,导致误报、panic、CI 卡死。
为什么 .golangci.yml 必须显式存在且位置严格
golangci-lint 在 Go Modules 项目中不会自动“猜”你想要什么规则。它只做一件事:找 .golangci.yml;找不到,就硬切回内置默认集(v1.54+ 仍含 golint 和 typecheck),而这两个在 Go 1.21+ 下极易因 AST 解析差异直接崩溃。
- 文件名必须是
.golangci.yml(不是.golangci.yaml、golangci.yml,也不能带 BOM) - 必须和
go.mod在同一目录;monorepo 中每个 module 都要单独放一份 - 缩进只能用空格,
run和linters是顶层字段,不是嵌套在别的 key 下 - CI 中别依赖“自动发现”,必须显式传参:
golangci-lint run --config=.golangci.yml
output.formats 和 issues 配置错一个,报告就失效
终端上看得见 ≠ CI 能解析 ≠ IDE 能跳转。输出格式必须匹配使用场景,否则就是“检查做了,但没人看见”。
-
output.formats必须显式声明:format: github-actions(用于 PR 标注)、format: json(用于脚本消费)、format: checkstyle(用于 Jenkins/SonarQube)——默认 terminal 输出对机器完全不可用 -
max-issues-per-linter: 0推荐设为 0(不限制),否则staticcheck查出 51 条就截断,深层问题直接消失 -
exclude-rules必须放在issues下才生效;写在linters-settings里等于没写 - 想忽略某个文件?用
exclude-rules+ 正则匹配path;想忽略某类报错文本?正则匹配text;两者是“且”关系,不是“或”
并发、超时、skip-dirs 不联动调优,检查就会卡死或漏报
高并发不是银弹。golangci-lint 的瓶颈不在 CPU,而在 go/types 加载、GC 压力和模块锁争抢。
立即学习“go语言免费学习笔记(深入)”;
-
concurrency: 2或3对中小项目更稳;大型项目可试4,但必须配合skip-dirs -
timeout: 2m适合本地开发;CI 建议5m起步,频繁超时先查是否启用了缓存(GOLANGCI_LINT_CACHE) -
skip-dirs至少包含:vendor、testdata、internal/gen、pb.go所在目录——否则errcheck会对proto.Unmarshal报一堆假错 -
modules-download-mode: readonly是必选项,尤其在 CI 或多 replace 场景下,否则并发解析会死锁
升级后配置静默失效的三个关键盲区
golangci-lint 升级(如 2.15+)常让旧配置“看起来正常,实际不生效”——它不报错,只是跳过。
-
exhaustive的配置键全变了:explicit-exhaustive-switch→explicit-exhaustive,check: map→check: mapliteral,ignore-enum-members→ignore-constants(值必须是字符串切片) -
--fast模式在 CI 中默认禁用所有 slow 类检查器(包括新版exhaustive和staticcheck),本地没开就显得“CI 多报、本地不报” - Go 版本差异会放大问题:Go 1.22+ 对泛型分析更细,
staticcheck耗时可能翻倍,若 timeout 没同步调大,就会误判为代码问题
最麻烦的从来不是写第一版配置,而是每次升级、换环境、加新 module 时,那些没报错却悄悄失效的字段——它们藏在缩进空格里、藏在路径层级里、藏在 issues 和 linters-settings 的边界上。


















