当前是Modules模式当且仅当go env GO111MODULE输出on或auto且go list -m成功返回模块信息；否则为GOPATH模式。
怎么判断当前是 GOPATH 模式还是 Modules 模式
别靠猜，直接运行两条命令：go env GO111MODULE 和 go list -m。前者输出 on 表示强制模块模式，off 表示彻底禁用（哪怕有 go.mod 也无视），auto（Go 1.16+ 默认）表示“有 go.mod 就用 Modules，否则 fallback 到 GOPATH”。后者如果成功返回类似 example.com/myapp v0.0.0-00010101000000-000000000000 的模块名，说明已进入 module 模式；报错 go: not in a module 才是纯 GOPATH 模式。
go build 报 cannot find module providing package 是 GOPATH 幻觉
这个错误几乎总是因为你在 module 模式下，还误以为把代码放在 $GOPATH/src/github.com/user/repo 就能自动被识别——其实不会。go build 在 module 模式下只认三类路径：require 声明的远程版本、replace 指向的本地或 fork 路径、以及 ./ 开头的相对路径。它完全不扫描 $GOPATH/src。
常见误操作包括：
- 项目根目录有
go.mod，但你仍把本地修改的依赖库硬塞进$GOPATH/src，却不加replace - 执行
go run main.go时不在 module 根目录下，导致找不到模块上下文 - CI 脚本没显式设
GO111MODULE=on，而本地开发机用了auto或on，造成行为不一致
replace 是 bridge，不是 bypass
replace 的作用不是绕过模块系统，而是显式桥接本地开发状态与模块依赖图。比如你正在改一个上游库，还没发版，就得在 go.mod 里写：
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
replace github.com/old/pkg => ../local-pkg
这条语句生效的前提是：go mod tidy 已运行过，且 go list -m all | grep old/pkg 确实显示来源是 ../local-pkg。否则说明 replace 没被加载——可能因为路径拼错、GO111MODULE=off、或者 go.mod 文件格式损坏（比如漏了换行）。
注意几个硬限制：
-
replace不影响 CI 构建，除非你把本地路径也提交进去（这会导致构建失败） -
replace后必须运行go mod tidy，否则不会写入go.sum，校验和缺失会触发go build报错 - 私有仓库路径（如
gitlab.example.com/group/lib）若没配GOINSECURE或GOPRIVATE，replace也会拉取失败
迁移老项目时 vendor/ 和 go.mod 的顺序不能错
历史项目常带 vendor/ 目录，这是 GOPATH 时代的产物。直接 go mod init 会让 go mod tidy 误读 vendor/modules.txt，选错版本甚至引入已废弃的 commit。
正确步骤只有三步，缺一不可：
- 删掉
vendor/目录（连同vendor/modules.txt） - 在项目根目录执行
go mod init example.com/myapp（模块名别用main） - 立即跑
go mod tidy，再根据报错补replace或调require版本
最后检查 go.sum 是否生成、go list -m all 是否列出所有预期依赖。最容易被忽略的是：迁移后仍保留 GO111MODULE=off 环境变量，这会让整个流程前功尽弃——module 模式根本没启动。
