根本原因是Go版本低于1.22或GOROOT/GOPATH配置错误，导致cmp、slices、maps、log/slog等标准库包无法识别；需确认go version ≥ 1.22、GO111MODULE=on，并确保go.mod存在且已执行go mod tidy和go build ./...。
golangci-lint 报 “package xxx not in GOROOT” 怎么办
这不是 golangci-lint 本身的问题，而是 Go 构建环境没准备好——它在尝试加载依赖时，连 cmp、slices、maps、log/slog 这些标准库包都找不到，说明 Go 版本太低或 GOPATH/GOROOT 混乱。
常见错误片段：
github.com/golangci/golangci-lint/cmd/golangci-lint imports cmp: package cmp is not in GOROOT (/usr/local/go/src/cmp)
这些包从 Go 1.21 开始才进入标准库（slices、maps、cmp）；log/slog 是 Go 1.21 引入，go/version 是 Go 1.22 加入的。所以根本原因是：
- 你用的 Go 版本 低于 1.22（比如还在用 1.19 或 1.20）
- 或者 GOPATH/GOROOT 被手动改错，导致
go list -json解析失败，golangci-lint 拿不到正确的 import graph - CI 环境中未显式设置
GO111MODULE=on，导致 module 模式未启用，依赖无法解析
验证方式：运行 go version 和 go env GOROOT GOPATH GO111MODULE，确认 Go ≥ 1.22 且 GO111MODULE=on。
立即学习“go语言免费学习笔记（深入）”；
本地能跑，CI 报 undefined: TestServer 怎么修
这类报错不是语法错误，是 golangci-lint 在分析阶段“看不懂”你的代码——它依赖 go list 构建 AST，一旦依赖图断了，就会把本该识别的类型/函数当成未定义。
典型触发场景：
-
go.mod没提交到 Git，CI 拉不到，go mod download失败 - 用了
replace指向本地路径（如replace example.com/lib => ../lib），但 CI 没同步那个目录 - Go 版本不一致：本地是 1.22，CI 流水线用的是 1.18，导致某些泛型或新 API 无法解析
- 没在 CI 中先执行
go build ./...验证基础构建是否通过——lint 是构建的子集，build 都过不了，lint 必然失败
修复动作要按顺序来：go mod tidy → go build ./... → 再跑 golangci-lint run。CI 脚本里别省这一步。
.golangci.yml 配置生效但 still 报依赖问题？检查这三个点
配置文件存在 ≠ 被正确加载。golangci-lint 对路径和加载逻辑非常严格，容易卡在细节上：
-
.golangci.yml必须和go.mod在**同一目录**；放在config/或tools/下无效 - 多 module 项目（如
api/和shared/各有go.mod）必须每个 module 目录下都有自己的.golangci.yml，不能只在根目录放一个 - CI 或 IDE 中没显式指定配置路径，例如：
golangci-lint run --config=.golangci.yml；不加--config参数时，它可能 fallback 到默认规则或读错位置
VS Code 的 Go 插件也一样：必须在设置里勾选「使用配置」并填对路径，否则会沿用缓存或全局默认，跟本地命令行行为不一致。
为什么跳过 docs/ 目录不是可选项，而是必做项
docs/ 通常是 swaggo/swag 自动生成的，里面包含 docs.go 和 swagger.json。这些文件有大量 // +build 注释、未使用的变量（如空 struct）、重复字符串字面量——golangci-lint 会认真检查它们，并报一堆无关警告（比如 SA1019 在生成代码里误判，goconst 报 JSON 字段重复）。
正确做法是在 .golangci.yml 的 run.skip-dirs 中明确排除：
run:
skip-dirs:
- docs
- vendor
- testdata别用 issues.exclude-rules 逐个匹配文件名——docs/doc.go 可能随 swag init 重建，路径不稳定；而 skip-dirs 是 lint 启动前就跳过整个目录扫描，更彻底、更可靠。
