Go Modules项目必须显式配置与go.mod同级的.golangci.yml,否则退回到启用golint、typecheck等已弃用或冗余linter的默认配置,导致误报、卡死或Go 1.21+下panic。

Go Modules 项目不配 .golangci.yml 就等于没开 lint —— 它会退回到启用 golint、typecheck 等已弃用或冗余检查的默认配置,轻则误报、卡死,重则在 Go 1.21+ 下直接 panic。
为什么 .golangci.yml 必须和 go.mod 同级
golangci-lint 不会递归查找配置文件,也不继承父目录配置。多 module 仓库(比如 api/ 和 shared/)中,每个子模块目录都得有自己的一份 .golangci.yml,否则它就当没这回事,默默切回默认模式。
- 常见错误现象:
golangci-lint run安静退出、零输出,但 CI 却爆一堆SA1019(弃用警告)或unused—— 这说明配置根本没加载 - 验证方式:运行
ls -a | grep golangci,确认是.golangci.yml(注意点开头 +yml小写),且与go.mod在同一目录 - CI 脚本里别依赖自动发现,必须显式传参:
golangci-lint run --config=.golangci.yml
.golangci.yml 缩进和语法错一点就全失效
YAML 对缩进极其敏感,run、linters、linters-settings 必须顶格平级;linters.enable 是列表,每项前必须是 - (短横 + 空格);冒号后必须有空格;不能用 Tab;不能复制带全角空格或 Zero Width Space 的网上示例。
- 典型误配:
linters-settings被缩进到linters下面,或run和linters缩进多了一格 → 整个配置被忽略,退回到仅启用govet、errcheck等约 10 个 linter 的“安全模式” - 推荐预检:装
yamllint,跑yamllint .golangci.yml验证基础语法 - 所有顶层字段必须严格平级,例如
output和run并列,不能嵌套
哪些 linter 必须启用,哪些必须禁用
默认启用集严重过时:golint 已归档、typecheck 和 go build 冗余且易与 Modules 冲突;而真正能挖出泛型误用、恒真判断、弃用 API 的 staticcheck、unused、gosimple 默认反而是关闭的。
- 最小有效组合(Go 1.21–1.23 兼容):
enable: [govet, errcheck, staticcheck, unused, gosimple] - 必须显式禁用:
disable: ["golint", "typecheck"](注意大小写,golint不是Golint) -
staticcheck推荐开启全部检查:linters-settings.staticcheck.checks: ["all"],它包含 SA1019(弃用警告)等关键项;若要关某条规则(如 SA1018),必须在checks里排除,而不是全局disable整个 linter
Modules 项目特有的三个关键配置项
Go Modules 的依赖解析逻辑和传统 GOPATH 完全不同,run 段必须显式约束,否则 lint 过程可能意外修改 go.sum 或卡死在生成代码上。
-
timeout: 2m:防止staticcheck在复杂泛型场景下超时 hang 住 -
modules-download-mode: readonly:禁止 lint 过程执行go mod download,避免 CI 中因网络或权限问题失败 -
skip-dirs: ["vendor", "testdata", "internal/gen"]:跳过vendor(冗余)、testdata(测试数据)、internal/gen(如pb.go、mock_*.go),否则errcheck会对proto.Unmarshal报错
最常被忽略的其实是 modules-download-mode: readonly —— 很多人只关注 linter 开关,却让 lint 在 CI 里反复尝试下载模块,最终超时失败;还有人把 skip-dirs 写成 skip_dirs(下划线),YAML 解析失败后整个配置静默失效。这些细节不校验,再好的规则也白搭。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











