golangci-lint run没报错但实际没检查，先查.golangci.yml是否存在且命名正确（仅认.golangci.yml）、与go.mod同级；若存在则验证缩进是否全为空格、linters-settings和run是否为顶层字段、多module项目是否每个module均单独配置；CI或IDE中必须显式指定--config=.golangci.yml参数，否则回落默认极简集。
golangci-lint run没报错但实际没检查？先查配置文件是否存在
最常见的情况是压根没配 .golangci.yml，或者名字写错了。它只认 .golangci.yml（不是 .golangci.yaml、golangci.yml 或 .golangci.yml.example）。文件必须放在和 go.mod 同级的目录下——不是 Git 仓库根目录，也不是 src/ 或 cmd/ 子目录。
验证方式很简单：
- 运行 ls -a 确认当前目录有 go.mod 和 .golangci.yml
- 执行 golangci-lint help linters 查看默认启用哪些 linter；如果只看到 govet、errcheck，说明配置没加载（因为 staticcheck、unused 默认是关的）
配置文件存在但 still no effect？检查路径、缩进与字段层级
即使文件名和位置都对，以下三处仍极易出错：
-
.golangci.yml必须用空格缩进，不能混入 Tab（YAML 解析器会静默失败） -
linters-settings和run是顶层字段，不是linters的子项；写成嵌套结构会导致整个配置被忽略 - 多 module 项目（如 monorepo 中的
api/和shared/）中，每个 module 目录都得有一份独立的.golangci.yml，父目录的配置不会继承
一个最小可用配置示例：
linters-settings:
staticcheck:
enable-all: true
linters:
enable:
- govet
- errcheck
- staticcheck
run:
skip-dirs:
- docs
- vendor
CI 或 IDE 里不生效？别依赖自动发现
golangci-lint 不会自动向上查找配置文件，也不会读取环境变量推导路径。在 CI 脚本或 IDE 配置中，必须显式指定：
- CI 中：用
golangci-lint run --config=.golangci.yml，不要只写golangci-lint run - VS Code：在设置中确认
"go.lintFlags"包含--config=.golangci.yml，且勾选「使用配置」选项 - GoLand：File Watchers 需手动填入完整命令，包括
--config参数
漏掉 --config 就等于没配——它会回落到极简默认集，你看到的“没报错”其实是“根本没跑你想用的检查器”。
为什么 local 正常、CI 报一堆 SA1019 却本地看不到？
这通常不是配置问题，而是环境不一致导致的解析差异：
- CI 中 Go 版本太低（GO111MODULE=off 导致无法正确解析依赖，进而让
staticcheck缺少类型信息，误判为“未使用”或漏报弃用 API - CI 拉取的代码缺少
go.mod或go.sum，或replace指向了本地路径，linter 解析失败后降级为默认规则集 - 本地用了
--fast模式（跳过unused等耗时 linter），而 CI 跑的是全量检查
真正关键的不是“有没有配置”，而是“配置是否在所有执行环境中被同等加载”。每次改完 .golangci.yml，务必在 CI 环境里重新运行一次带 --config 的完整命令并观察输出，否则很容易以为修好了，其实只是没触发。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
