根本原因是当前目录未被Go识别为有效模块作用域，常见于项目根目录在$GOPATH/src下、GO111MODULE非on、无.go文件、go.mod命名非法、GOROOT配置错误、GOPRIVATE未设致私有包404等情形。
go build 报 cannot find module providing package 是 GOPATH 路径残留导致的
这不是 Go 找不到包，而是它根本没去 $GOPATH/src 下扫描——只要项目有 go.mod 且 GO111MODULE=on（或 auto 且当前目录含 go.mod），Go 就彻底忽略 $GOPATH/src。常见现象是：你把代码放在 $GOPATH/src/github.com/user/repo 里，import "github.com/user/repo/utils" 却报错。
- 确认是否真在 module 模式：
go list -m成功返回模块名才有效；go env GO111MODULE输出off就直接退回到 GOPATH 模式 - 别把项目根目录设在
$GOPATH/src下再执行go mod init，否则 Go 会错误推导模块名为github.com/user/repo，但你本地可能根本没托管在 GitHub - 删掉整个
vendor/目录再初始化，否则go mod tidy可能误读旧 vendor 中的版本信息，选错依赖
本地 import 路径和 go.mod 声明不一致引发漂移
比如原 GOPATH 项目里写 import "utils" 或 import "myproj/config"，迁移到 Modules 后这些路径不再合法。Go 不会自动映射，也不会 fallback 到 $GOPATH/src，而是直接报错。
- 子目录引用（如
./config、./internal/db）保持不变，点号路径始终有效 - 跨项目引用必须用完整模块路径：
import "github.com/old-org/lib/v2"，而不是"lib" - 用
grep -r 'import "' . --include="*.go" | grep -v '^\.' | grep -v '"\./'快速扫出非点号路径的 import，逐个核对是否匹配go.mod第一行的模块名 - 如果模块名是
example.com/myapp，所有外部引用它的代码也必须写import "example.com/myapp/sub"，否则别人go get不到
GO111MODULE=off 导致 CI 和本地行为不一致
这是最隐蔽的漂移源头：有人本地设了 GO111MODULE=off，go mod tidy 不生效、go.sum 不生成、依赖版本不锁定；结果本地能跑，CI 构建失败或运行时 panic。
- CI 脚本开头必须显式加
export GO111MODULE=on，不能依赖默认值 - 团队应禁止提交未声明的
// indirect依赖，它们容易被go mod tidy静默删掉，造成构建差异 -
go list -m all输出的依赖树才是真实生效版本，别拿vendor/里的内容当依据——Modules 默认不读 vendor，除非加-mod=vendor - 私有仓库必须配
GOPRIVATE=git.example.com/*，否则 Go 仍走proxy.golang.org，拉不到内网地址，或校验失败
replace 指向本地路径却在 CI 失效
replace github.com/some/pkg => ../some-pkg 在本地调试很顺，但 CI 构建时 ../some-pkg 不存在，go build 直接失败。这不是 bug，是设计使然。
立即学习“go语言免费学习笔记（深入）”；
- replace 仅用于开发阶段临时验证，上线前必须删掉，改用真实 tag 或 commit hash
- 若需长期使用 fork，应 push 到可访问的远程仓库，然后 replace 指向该地址 + 版本，例如：
replace github.com/some/pkg => github.com/your-fork/pkg v0.0.0-20231015120000-abcdef123456 - CI 环境中禁止提交含本地路径的 replace，可在 PR 检查脚本里加
grep -q '=> \.\.' go.mod并拒绝合并 - 真正要锁定版本，优先用
go get github.com/some/pkg@v1.2.3+go mod tidy，而不是靠 replace 绕过版本约束
