报错“package xxx is not in GOROOT”本质是Go工具链未按预期路径解析包，主因是模块模式（GO111MODULE≠off）下未正确初始化go.mod或路径不匹配：需确保go mod init项目名与目录一致、import路径以module名开头、关闭GO111MODULE=off或规范使用go mod tidy同步依赖。
go build 报错：package xxx is not in GOROOT
这是版本退回后最典型的症状。你删了 go.mod 或手动降级某个依赖，但 go.sum 里还留着旧哈希，或者本地 pkg/mod 缓存里混着多个版本的模块——Go 工具链会拒绝加载非标准路径下的包，直接报这个错。
别急着删整个 pkg/mod，先做三件事：
- 运行
go mod tidy，它会清理未引用的依赖，并按go.mod当前声明重新拉取、校验、写入go.sum - 如果报 checksum mismatch，说明
go.sum里存的哈希和实际下载内容不一致，此时加-x参数跑一次go mod download -x看具体哪个模块出问题 - 确认你没在
replace里硬编码指向本地路径（比如replace github.com/some/pkg => ../some/pkg），版本退回后本地代码结构可能已不匹配
依赖树里出现 indirect 但编译时找不到符号
indirect 标记只表示该模块不是你直接 import 的，而是被其他依赖带进来的。版本退回后，上游模块可能删了某个导出函数，或改了方法签名，而你的代码还在用旧 API —— 这时候编译器不会报“找不到包”，而是报“undefined: xxx”。
查清调用链很关键：
立即学习“go语言免费学习笔记（深入）”；
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 用
go mod graph | grep 'target-module'查谁引入了目标模块 - 再用
go list -m all | grep 'target-module'看当前 resolve 到的是哪个版本 - 如果发现多个版本共存（比如 v1.2.0 和 v1.5.0 同时在图里），说明有依赖冲突，得靠
require显式指定版本来统一
go get -u 降级失败：‘no matching versions’
go get -u 默认只升不降，想退到 v1.3.0 却提示找不到版本，通常是因为：
- 模块没打 tag，只有 commit hash 可用，这时得用
go get github.com/user/repo@abcd123 - 模块启用了 Go module proxy（如 proxy.golang.org），而该 proxy 缓存里没有你要的旧版，可临时关掉：
GOPROXY=direct go get github.com/user/repo@v1.3.0 - v1.3.0 其实存在，但模块名带 major version（如
github.com/user/repo/v2），你写成了v1路径，Go 不认
CI 构建成功但本地失败：GOPATH 和 GOBIN 残留干扰
本地环境里如果还开着 GOPATH，且里面存着旧版模块源码，go build 可能偷偷从那里加载，绕过 go.mod 约束。尤其当你用过老版本 Go（go install 过工具时，容易残留。
干净排查步骤：
- 检查
go env GOPATH输出，如果非空，临时清掉：unset GOPATH（Linux/macOS）或set GOPATH=（Windows） - 删掉
$GOPATH/bin下可能影响构建的二进制（比如旧版protoc-gen-go） - 确认没设置
GOBIN，否则go install会写到非预期位置，干扰后续go run
版本退回不是单纯改个数字的事，真正卡住人的往往是缓存、代理、路径和隐式依赖之间的微妙冲突。动手前先看 go mod graph 和 go list -m all，比盲目删文件有用得多。
