CI报undefined的根本原因是Go环境与模块解析不一致，具体包括GO111MODULE未启用、Go版本不兼容、golangci-lint版本混乱、skip-dirs配置不当、缓存路径不可持久及exhaustive配置升级适配错误。
本地 golangci-lint run 正常，CI 却报一堆 undefined: xxx，根本不是配置问题，而是 Go 环境和模块解析没对齐。
CI 报 undefined 的真实原因
这不是 linter 本身的问题，是它依赖的 Go 编译器前端在 CI 里压根没正确加载包信息。常见触发点有三个：
-
GO111MODULE环境变量未设或设为off，尤其在旧版 Go（ -
go.mod文件没提交，或者replace指向了本地路径（如replace example.com/foo => ../foo），CI 拉不到对应代码 - CI 使用的 Go 版本不支持项目中用到的语法（比如泛型、
~T类型约束），导致go list -json解析失败，linter 就收不到 AST
验证方法很简单：在 CI 脚本里加一行 go build ./...，如果这步都过不了，golangci-lint 必然失败。
PATH 和二进制版本必须严格一致
CI 里跑出的版本号和本地不一样，就别指望行为一致。尤其是 golangci-lint 2.15+ 对 exhaustive 检查器做了配置语义变更，老版本配置在新版本下可能被忽略或误读。
立即学习“go语言免费学习笔记（深入）”；
- CI 中不要用
curl | sh临时装——它可能拉到缓存里的旧版；固定指定版本，比如v1.54.2 - 确认
$(go env GOPATH)/bin在PATH里，且排在系统默认路径之前（避免误调用系统里残留的旧二进制） - CI 启动时加
golangci-lint --version和go version打印日志，比猜省半小时
skip-dirs 和缓存路径不能只靠本地经验
本地跳过 vendor/ 是为了快，CI 里跳过还多一层意义：防止生成代码污染分析结果。但漏掉 generated/ 或 proto/ 目录，staticcheck 就会在 protobuf 生成文件里狂报错，掩盖真正该修的问题。
-
--skip-dirs至少包含：vendor,generated,protobuf,testdata（注意用英文逗号分隔，无空格） -
GOLANGCI_LINT_CACHE必须指向可持久化路径（如/tmp/golangci-cache），否则每次都是冷启动，耗时翻倍 - 别信
--fast能解决一切——它会跳过unused和goconst，但在 CI 主流程里关掉这些，等于主动放弃两道关键质量门禁
exhaustive 配置升级后最易踩坑
golangci-lint 2.15 把 exhaustive 的配置项全换了，旧配置还能读，但含义已不同。比如原来写 explicit-exhaustive-switch: true，现在得改成 explicit-exhaustive: true，且要配合 check: [switch, mapliteral] 才生效。
-
ignore-enum-members已废弃，换成ignore-constants: ["ErrUnknown", "StatusPending"]（注意是切片） - 如果项目用了自定义正则过滤类型，检查器现在只认
ignore-types，旧的字符串值不会自动转成列表 - 这个检查器被划入
slow分组，如果你的 CI 流水线按性能标签筛选 linter，它可能直接被跳过——得手动加回enable列表里
配置不是写完就完事，每次升级都要对照官方文档逐项核对，尤其当报告里突然少了某些 switch 分支告警，或者提示文本变了却没意识到是配置失效。
