根本原因是当前目录未被识别为模块根目录，即GO111MODULE=off或项目路径位于$GOPATH/src下触发GOPATH模式降级，导致go.mod被忽略；需确认go env GO111MODULE输出为on且go list -m能正常返回模块名。
go mod init 后为什么 go build 还报 “cannot find module providing package”
根本原因不是依赖没下载，而是当前目录没被识别为 module。Go 不会自动把任意路径当模块——必须有 go.mod 且 GO111MODULE 没被关掉。
检查方式很简单：
- 运行
go env GO111MODULE：输出off就立刻失效，哪怕有go.mod也视而不见 - 运行
go list -m：成功返回模块名说明已进 module 模式；报错go: not in a module就是还在 GOPATH 模式下硬扛
常见诱因是项目路径撞上了 $GOPATH/src/xxx 结构（比如你把项目放在 ~/go/src/github.com/user/app），即使有 go.mod，Go 也可能 fallback 到旧模式——这不是 bug，是 auto 模式的默认行为。
为什么 replace 在 GOPATH 模式下完全不生效
replace 是 module 机制的专属指令，只在 go.mod 文件里起作用。GOPATH 模式下 Go 根本不读 go.mod，自然无视 replace，也不会校验 go.sum。
立即学习“go语言免费学习笔记（深入）”；
典型现象：
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 你在
go.mod里写了replace github.com/foo => ./local-foo - 但
go run main.go仍去拉远程github.com/foo，甚至报错找不到 - 此时八成是
GO111MODULE=off或者当前不在 module 路径下
注意：replace 只影响构建时的 import 路径解析，不影响 go get 行为；想让本地修改参与构建，必须确保整个流程跑在 module 模式下。
go install 的二进制落盘路径为什么有时进 $GOPATH/bin，有时进 $HOME/go/bin
这和 module 模式无关，只取决于 GOPATH 环境变量是否设置，以及 Go 版本对默认值的处理逻辑。
- Go 1.16+ 默认不设
GOPATH，此时go install会用$HOME/go作为隐式GOPATH，二进制落到$HOME/go/bin - 如果你显式设置了
GOPATH=/opt/mygopath，那go install就一定写到/opt/mygopath/bin -
GOROOT完全不影响这个路径——它只管 Go 自身安装位置，和你的项目、二进制输出无关
CI 脚本里建议显式导出 GOPATH，避免不同机器因环境变量缺失导致 go install 输出路径不一致，进而引发 PATH 查找失败。
老项目迁移时 vendor/ 目录为什么反而导致 go mod tidy 选错版本
go mod tidy 在遇到 vendor/ 时会尝试读取其中的 modules.txt（如果存在），并据此反推依赖版本——但这不是权威来源，尤其当 vendor/ 是手工维护或来自旧工具生成时，版本信息往往过时或残缺。
迁移前务必：
- 先删掉
vendor/目录（rm -rf vendor） - 再执行
go mod init和go mod tidy - 不要保留旧
vendor/modules.txt，它会干扰 module 初始化逻辑
真正可靠的版本来源只有 go.mod 中的 require 行和 go.sum 中的哈希——vendor/ 在 module 时代只是可选缓存，不是真相本身。
