根源在于PATH中混入旧版go或GOPATH被shell配置覆盖：which go返回/usr/local/go/bin/go但go env GOPATH为空或异常，说明执行的go二进制与环境变量读取不匹配。
go env GOPATH 和 which go 不一致怎么判断根源
这是最直接的冲突信号：终端里 which go 返回 /usr/local/go/bin/go，但 go env GOPATH 却是空、/usr/lib/go 或其他异常路径。说明你当前执行的 go 二进制和它读取环境变量的方式不匹配——大概率是 PATH 中混入了旧版系统包（如 Ubuntu 自带的 /usr/bin/go），或者 GOPATH 被某个 shell 配置文件覆盖但未生效。
验证步骤：
- 运行
which go看实际调用路径 - 运行
go version确认是否 ≥ 1.16（否则不默认启用 Modules） - 运行
go env GOPATH GOROOT对比输出 - 检查
~/.zshrc、~/.bash_profile、/etc/profile里是否有硬编码的GOPATH=或GOROOT=行
GO111MODULE=off 导致本地 GOPATH 包无法被识别
即使你把代码放在 $GOPATH/src/github.com/user/repo 下，只要 GO111MODULE=off 没生效或项目根目录有 go.mod，go build 就不会扫描 $GOPATH/src —— 它只认 replace、require 和当前目录下的相对 import。
常见错误现象：
立即学习“go语言免费学习笔记（深入）”；
-
go run main.go报cannot find module providing package github.com/user/lib，但该包明明在$GOPATH/src/github.com/user/lib -
go list -m报错go: not in a module，说明没进入 module 模式，但go env GO111MODULE却是auto—— 很可能当前目录没有go.mod，且不在$GOPATH/src的标准路径下 - 误以为删掉
$GOPATH就能解决问题，结果go mod tidy仍拉错版本，因为模块缓存$GOPATH/pkg/mod还在
残留模块缓存导致依赖版本错乱
rm -rf /usr/local/go 只清了 Go 二进制和标准库，$GOPATH/pkg/mod 和 go build 生成的中间产物还在。新装的 Go 一跑就自动读这些旧缓存，可能拉取已被废弃的 commit、校验失败、甚至编译出带旧符号的二进制。
必须清理的三项：
-
go clean -cache -modcache -i：清构建缓存、模块下载缓存、已安装命令（如go install生成的可执行文件） -
rm -rf $(go env GOPATH)/pkg/mod：手动删模块缓存（注意：首次go build会慢，但能彻底避免版本错乱） -
go env -w GOSUMDB=sum.golang.org：恢复默认校验服务，避免因之前设为off或私有地址导致后续依赖解析失败
replace 指向本地 GOPATH 路径却无效
很多人写 replace github.com/old/lib => $GOPATH/src/github.com/old/lib，但这是错的：replace 不支持环境变量展开，$GOPATH 会被当字面量处理，导致路径不存在。
正确做法：
- 用绝对路径：例如
replace github.com/old/lib => /home/user/go/src/github.com/old/lib - 用相对路径（推荐）：如果本地包和当前项目在同一父目录，写成
replace github.com/old/lib => ../old-lib - 确保被替换路径下有
go.mod文件，否则go mod tidy会忽略它 - CI 构建时禁用本地路径
replace，否则必然失败；开发阶段可用，但不要提交到主干
真正容易被忽略的是：模块模式下，go 命令根本不看 $GOPATH/src，哪怕你把代码放对位置、环境变量也设对了，只要没显式 replace 或 require，它就当那块代码不存在。这不是 bug，是设计使然。
