golangci-lint安装后默认仅启用极少数linter,必须配置.golangci.yml(与go.mod同级、纯空格缩进、顶层字段linters.enable明确启用govet/errcheck/staticcheck等)才真正生效。

装完就能用,但不配就等于没装——golangci-lint 默认只启用极少数 linter,大部分实用检查(比如未处理错误、无效赋值、死代码)默认关闭,必须手动启用配置文件才能真正起效。
安装后必须验证的三件事
很多人卡在“明明装了却没报错”,其实是没确认清楚环境状态:
-
golangci-lint --version能输出版本号,说明二进制可执行 -
which golangci-lint确认路径在$GOPATH/bin或$PATH里,否则 IDE/CI 找不到 -
go env GOPATH和go version要匹配:若项目用 Go 1.21,而本地是 Go 1.19,govet或typecheck可能静默跳过或报错
.golangci.yml 文件必须放在项目根目录
这个文件名和位置是硬编码逻辑,golangci-lint run 不会向上递归查找父目录,也不会读 config.yaml 这类变体名:
- 文件名只能是
.golangci.yml、.golangci.yaml、.golangci.toml或.golangci.json,推荐用.golangci.yml - 必须放在
go.mod所在目录(即模块根),否则run会提示no go files to analyze - 空配置文件(仅写
linters:)会导致所有 linter 全部禁用,等价于没配
最简可用配置要包含 enable 列表
不写 enable 就等于关掉几乎所有检查。以下是最小但实际有效的配置片段:
立即学习“go语言免费学习笔记(深入)”;
linters:
enable:
- govet
- errcheck
- staticcheck
- unused
- ineffassign
- gosimple说明:
-
govet是 Go 官方工具,检查类型不匹配、结构体字段未使用等基础问题 -
errcheck检查err是否被忽略,但注意它不检查if err != nil后是否 return,那是staticcheck的SA5011规则 -
staticcheck和gosimple功能有重叠,但前者更重语义(如空循环、冗余条件),后者专注简化(如用strings.TrimSpace替代strings.Trim) - 别加
golint:它已归档,golangci-lintv1.50+ 默认禁用,强行启用会报错
容易被忽略的 run 配置项
没有这些,大项目可能超时失败或漏检:
-
run: timeout: 3m—— 默认无超时,但 CI 中常因网络拉模块卡住;设为 3~5 分钟较稳妥 -
run: skip-dirs: [vendor, mocks, testdata]——vendor目录不检查,避免第三方代码干扰;mocks是常见生成代码目录,也建议跳过 -
run: concurrency: 4—— 默认用 CPU 核心数,并发太高可能触发系统 OOM,尤其在 CI 容器中 -
run: tests: true—— 显式开启对*_test.go的检查,否则默认跳过测试文件
复杂点在于:skip-dirs 的路径是相对于当前工作目录的,不是相对于配置文件;如果在子目录下执行 golangci-lint run ./sub,skip-dirs 仍按项目根来算,这点极易踩坑。


















