Go Modules项目必须显式配置.golangci.yml，否则回退到启用golint、typecheck等过时linter的默认配置，易导致panic、超时或CI中断；多模块项目需每个go.mod同级目录单独配置，文件名、位置、缩进均须严格匹配。
Go Modules 项目必须显式配置 .golangci.yml
不配就等于裸奔——golangci-lint 在 Go Modules 项目中不会自动适配模块语义，而是回退到内置默认配置，其中仍启用 golint（已归档）、typecheck（与 go build 冗余）等过时或冲突 linter。这些检查在 go.mod 声明 go 1.21+ 的项目里极易 panic 或超时。
常见表现：golangci-lint run 卡住 2 分钟以上、报 failed to load program: typechecker error、CI 中因 govet 检查失败中断。
根本原因：Go Modules 本身不提供 lint 规则，工具无法从 go.mod 推导出合理检查边界，必须靠配置文件显式声明作用域和行为。
多模块仓库（monorepo）下配置不能只放根目录
如果你的仓库包含多个 go.mod（比如 services/auth、libs/logging），单靠根目录一份 .golangci.yml 会失效——golangci-lint 默认只读取当前工作目录下的配置，且 issues.exclude、run.cwd 等字段不支持通配路径继承。
- 每个子模块目录下都得放一份
.golangci.yml，且必须与对应go.mod同级 -
run.cwd要设为.（相对当前模块根），避免跨模块误扫 -
issues.exclude应按子模块实际路径写，例如services/auth/internal/gen/.*，不能写成internal/gen/.*（否则在libs/logging下执行时匹配不到） - 生成代码（
pb.go、mock_*.go）必须用skip-dirs或exclude-rules显式排除，否则errcheck会对proto.Unmarshal报未处理错误
output.formats 和 issues 配置决定报告是否“真生效”
配了 .golangci.yml 不代表 CI 或 IDE 能看到问题——默认输出是带颜色的终端文本，机器完全无法解析。
关键项必须显式设置：
-
output.formats：CI 场景用github-actions（生成::error file=::格式），本地存档用json（但要加print-issued-lines: true才有源码上下文） -
issues.max-issues-per-linter: 0：CI 中禁用截断，否则staticcheck超过 50 条就静默丢弃 -
issues.max-same-issues: 0：本地调试时关掉合并，避免同一类错误被折叠成一条 -
exclude-rules必须放在issues下层，写在linters-settings里完全不生效
linters.enable 和 disable 必须手动控制，别信“默认合理”
v1.54+ 默认启用集仍含危险项，必须主动裁剪：
- 必须
disable: golint（官方已归档，无维护，与 Go 1.21+ AST 不兼容） - 必须
disable: typecheck（go build已覆盖，且在 Modules 下易触发解析 panic） -
enable清单建议最小化：只留govet、errcheck、staticcheck、unused、ineffassign -
staticcheck.checks: ["all"]要显式开启，否则默认不启用 SA1019（弃用警告）等关键检查 -
errcheck.check-blank: false关掉对_ = os.Remove()类写法的误报
最易被忽略的一点：配置文件名必须严格为 .golangci.yml（不是 .yaml），且缩进只能用空格——任一偏差都会导致整个配置被跳过，工具静默回退到默认集，连 warning 都不给。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
