必须手动创建.golangci.yml,因为golangci-lint默认配置版本不一致、自动启用冗余linter、不跳过vendor/testdata等目录、缺乏关键检查项(如type-assertions),且CI与本地行为不统一。

装完 golangci-lint 后,不配 .golangci.yml 就直接跑 golangci-lint run,大概率会报一堆你没打算管的警告,比如 golint 已弃用、typecheck 重复、lll 行长超限——这不是工具问题,是默认配置没对齐你的项目实际需求。
为什么必须手动建 .golangci.yml 而不是依赖默认?
golangci-lint 的“默认启用列表”在不同版本间有变动(例如 v1.53+ 默认禁用 golint,但 v1.49 还开着),且它会自动启用所有已安装 linter 的子集,包括你根本用不到的 dupl(重复代码检测)或 goconst(字面量提取)。不显式声明,就等于把检查权交给工具猜。
- 默认行为不包含
skip-dirs,vendor/、testdata/、internal/都会被扫,徒增耗时和噪音 - 没有
linters-settings时,errcheck不报告类型断言错误,gosimple可能误报泛型简化建议 - CI 环境里若没配置文件,
golangci-lint会 fallback 到内置最小集,跟本地结果不一致
.golangci.yml 最小可用配置怎么写?
从能跑通、不报错、不误伤开始,不是一上来就堆满 20 个 linter。以下是最简但生产可用的骨架:
run:
timeout: 2m
concurrency: 4
skip-dirs:
- vendor
- testdata
- internal
<p>linters:
enable:</p><ul><li>govet</li><li>errcheck</li><li>staticcheck</li><li>unused</li><li>ineffassign</li></ul><p>linters-settings:
errcheck:
check-type-assertions: true
check-blank: false
staticcheck:
checks: ["all"]</p>-
skip-dirs必加:vendor是 Go Modules 时代最常见误扫目录;testdata里常有故意写的坏代码用于测试 - 只开 5 个核心 linter:
govet查基础语义,errcheck防 panic,staticcheck替代旧版go vet做深度分析,unused和ineffassign清理死代码 -
errcheck.check-type-assertions: true是关键:否则v, ok := i.(MyStruct)这种写法不会被检查,容易漏掉类型断言失败路径
验证配置是否生效的三步检查法
别只信 golangci-lint --version 输出了版本号,要确认它真按你的规则在跑:
立即学习“go语言免费学习笔记(深入)”;
- 在项目根目录执行
golangci-lint run --no-config:应看到大量额外警告(比如golint报错),证明你当前的.golangci.yml确实被加载了 - 删掉
linters.enable下的- unused,再跑golangci-lint run -E unused:应报错can't find linter "unused",说明配置文件控制力有效 - 在某个
.go文件顶部加// nolint: unused,再运行golangci-lint run:该文件的未使用变量警告应消失,证明注释跳过机制工作正常
容易被忽略的路径和权限细节
很多“配置写了但不生效”的问题,根源不在 YAML 语法,而在环境链路断裂:
-
golangci-lint查找配置文件是从当前工作目录向上遍历,不是从go.mod所在目录——所以cd cmd/myapp && golangci-lint run会找不到项目根目录下的.golangci.yml - 在 CI 中用
docker run或远程 runner 时,$(go env GOPATH)可能为空,go install安装的二进制默认落在~/go/bin,而 runner 用户可能没读取~/.bashrc,导致 PATH 里没有golangci-lint -
skip-files不支持 glob 通配符,写- "*.test.go"无效;必须写成- "helper_test.go"或正则形式skip-files: ["^.*_test\.go$"]
配置不是一次写完就结束的事——当团队引入新 linter(比如 gosec 检查安全漏洞),或升级 Go 版本后 staticcheck 报出新规则,.golangci.yml 就得同步调整。它本质上是你项目的静态检查契约,而不是一个安装附赠的装饰品。


















