Go Modules项目必须显式配置.golangci.yml,否则golangci-lint会回退启用已弃用linter(如golint、typecheck),在Go 1.21+下易panic或超时,与工具版本无关。

Go Modules 项目必须显式配置 .golangci.yml,否则 golangci-lint 会启用已弃用 linter(如 golint、typecheck),在 Go 1.21+ 下极易 panic 或超时——这和你装的是 v1.54 还是 v2.0.0 没关系,只和有没有配置文件有关。
为什么 golangci-lint 版本共存不解决根本问题
很多人以为升级到 golangci-lint@v2 就能自动规避旧版问题,但实际不是:v1 和 v2 的配置 schema 不兼容,且两者都默认回退到内置“默认配置”(含 golint 等),只要没配 .golangci.yml,就一定会出错。v2 还额外要求顶层声明 version: "2",否则直接报错解析失败。
- v1 配置(无
version字段)在 v2 下加载失败,提示unknown field "linters-settings"类错误 - v2 配置在 v1 下运行会静默忽略大部分字段,退化为默认行为
- CI 中混用版本(如 GitHub Actions 用
v1.54.2,本地用v2.0.0)会导致检查结果不一致
多版本环境下必须统一的三项配置底线
无论你本地用 v1 还是 v2,只要项目是 Go Modules(即含 go.mod),以下三项必须出现在 .golangci.yml 中,否则 lint 必然异常:
-
run.modules-download-mode: readonly—— 防止 lint 过程意外修改go.sum,尤其在 CI 中因权限问题卡死 -
run.skip-dirs显式排除vendor、testdata、internal/gen等生成目录,否则errcheck会对proto.Unmarshal报错 -
linters.disable明确关掉golint(已归档)和typecheck(与go build冗余),避免 AST 解析冲突
如何判断当前项目该用 v1 还是 v2 配置
看两个硬指标,不是看个人偏好:
立即学习“go语言免费学习笔记(深入)”;
- 如果
go.mod里写的是go 1.23或更高,且用了range over func、iter.Seq、slog等新特性,必须用 v2 配置(v1 的staticcheck不识别这些) - 如果团队 CI 流水线锁定了
v1.54.2(比如某些企业内网镜像只同步到 v1),那就必须用 v1 schema,并确保linters-settings.staticcheck.checks不设["all"](v1 的all包含大量误报项) - 运行
golangci-lint --version后再执行golangci-lint run -v,观察日志里是否出现enabled linters: [govet errcheck staticcheck ... golint]—— 出现golint就说明配置没生效,别管版本号是多少
最常被忽略的一点:golangci-lint 的版本管理本身不解决配置漂移。你在本地 go install 了 v2,但 CI 用的是 action@v3(默认拉 v1.54),那配置文件就必须兼容 v1;反之亦然。真正起作用的永远是配置文件是否存在、是否正确、是否被读取——而不是二进制名里带不带 “v2”。


















