中小团队必须显式声明.golangci.yml的version: "2"、禁用非共识规则,并在CI/IDE中强制传参--config=.golangci.yml;否则golangci-lint v2默认不加载配置,仅运行极简内置规则集(govet+staticcheck子集),导致配置形同虚设。

直接上结论:中小团队用 .golangci.yml 模板,必须显式声明 version: "2",禁用所有非共识规则,且 CI/IDE 中必须带 --config=.golangci.yml 参数——漏掉任一环节,配置就等于没写。
为什么你的 .golangci.yml 总是不生效
根本原因不是规则写错,而是 golangci-lint v2 默认不自动查找配置文件。它不会向上遍历父目录,也不读环境变量或 GOPATH 下的默认路径。
- CI 脚本里只写
golangci-lint run→ 实际运行的是极简内置规则集(只含govet和staticcheck的子集),你看到“没报错”其实是“根本没跑你配的规则” - VS Code 的
go.lintFlags没加--config=.golangci.yml或没勾选「使用配置」→ 编辑器里波浪线全消失,但错误其实还在 - GoLand 的 File Watcher 命令里没填完整路径(比如写成
--config=golangci.yml少了点)→ 静默 fallback 到默认行为
中小团队可用的最小可行模板(v2 schema)
这个配置满足“能落地、易维护、不踩坑”三原则,已剔除重叠、低价值或需额外上下文的 linter:
version: "2"
run:
timeout: 3m
concurrency: 4
skip-dirs:
- vendor
- testdata
- mocks
- gen
linters:
enable:
- govet
- errcheck
- staticcheck
- unused
- ineffassign
- gofmt
- goimports
- gocyclo
disable:
- golint # 已弃用
- typecheck # go build 已覆盖
- dupl # 误报率高,维护成本大于收益
linters-settings:
gocyclo:
min-complexity: 12
gofmt:
simplify: true
goimports:
local-prefixes: "github.com/yourorg/yourproject"
issues:
max-issues-per-linter: 30
max-same-issues: 3
exclude-rules:
- path: "_test\.go"
linters:
- errcheck
- path: ".*mock.*"
linters:
- errcheck
- unused
注意:goimports 的 local-prefixes 必须按你项目实际模块路径填,否则 import 分组会错乱;exclude-rules 是跳过生成代码/测试桩的唯一可靠方式,别用 skip-dirs 粗暴排除整个目录——有些测试文件需要检查,但 mock 文件不需要。
CI 和本地执行必须加的参数
本地开发和 CI 是两个独立执行环境,但都绕不开同一个硬约束:golangci-lint 不会猜你要用哪个配置。
- 本地命令建议封装进
Makefile:lint: golangci-lint run --config=.golangci.yml --fix(--fix只用于本地,CI 里禁用) - GitHub Actions 示例关键行:
golangci-lint run --config=.golangci.yml --out-format=github-actions - GitLab CI 同理,必须显式传
--config,且推荐加--fast加速增量检查 - 如果用了
pre-commit,钩子里的命令也必须带--config,否则提交时 lint 失效
容易被忽略的兼容性雷区
v2 配置不是 v1 的简单升级,而是 schema 重构。很多团队卡在“明明照着旧文档抄,却报错说字段不存在”,本质是版本错位。
-
version: "2"必须写在第一行,且是字符串(不是数字);缺了这行,golangci-lint v2 会拒绝加载配置 -
enable-all: true在 v2 中已被移除,改用presets或显式enable,混用会静默失效 - 如果你的项目用了 Go 1.23+ 新特性(如
range over func、iter.Seq),确保启用copyloopvar和intrange,否则静态检查会漏掉严重 bug -
go env GOPATH输出的 bin 目录必须在PATH里,否则即使装了golangci-lint,command not found依然会发生
最常出问题的不是规则多寡,而是配置路径、版本声明、执行参数这三个点没对齐。只要这三个点稳了,剩下的就是按需增减 linter 的事。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











