Go项目必须使用go mod，因其是解决构建失败、协作混乱和上线不一致的刚需；go build报“cannot find module providing package”即因未初始化模块，Go 1.16+默认启用模块模式且只认go.mod路径。
Go项目必须用模块（go mod），不是“推荐”，而是解决实际构建失败、协作混乱和上线不一致的刚需。
为什么 go build 会突然报错：”cannot find module providing package“
这是没初始化模块最典型的症状。Go 1.16+ 默认启用模块模式（GO111MODULE=on），如果项目根目录没有 go.mod，go build 就不会去 GOPATH/src 查找依赖，而是直接放弃——它只认模块路径。
- 旧项目迁移：在项目根目录运行
go mod init myproject
，自动生成go.mod - 别手动写
go.mod：它由go mod tidy自动维护，手改容易漏掉间接依赖或版本约束 - 如果项目用了私有仓库（如
git.internal.com/foo/bar），记得提前设GOPRIVATE=git.internal.com，否则go get会因校验失败卡住
go.sum 不是可选文件，它是构建确定性的唯一防线
go.sum 记录每个依赖模块的校验和（SHA256），作用不是“防篡改”，而是确保你本地下载的 v1.12.0 和同事、CI 服务器下载的是**完全相同的字节内容**——哪怕作者删库重发同名 tag，哈希也会变，go build 就会报错中断。
- 不要提交时删掉
go.sum：它和go.mod是一对，缺一不可 - 遇到
checksum mismatch：通常是你本地缓存损坏，执行go clean -modcache && go mod download
重建即可 - CI 环境必须校验
go.sum：加一行go list -m -json all | jq -r '.Sum' | sort > .sum-expected && cmp -s .sum-expected go.sum || (echo "go.sum changed!" && exit 1)
能防依赖被悄悄替换
多个项目共用同一依赖的不同版本？go mod 天然支持，GOPATH 根本做不到
比如你的项目直依赖 github.com/gorilla/mux v1.8.0，而引入的 SDK 又依赖 v1.7.4，go mod 会同时保留两个版本，在各自包路径下分别加载——因为模块路径 + 版本号构成唯一标识，和 GOPATH/src 下只能存一份的硬冲突逻辑完全不同。
- 验证方式：运行
go list -m all | grep mux
，你会看到两行输出，带不同版本号 - 升级某依赖但不影响其他：用
go get github.com/gorilla/mux@v1.9.0
，它只改当前项目的require行，不碰 SDK 的间接依赖 - 注意
replace的副作用：在go.mod里写replace github.com/gorilla/mux => ./local-mux后，所有依赖该模块的地方都会走本地路径，调试方便，但上线前必须删掉，否则 CI 构建失败
真正容易被忽略的点是：模块路径（module 指令后的字符串）一旦发布到公共仓库，就不该轻易改——它不仅是导入路径，更是 Go 生态里模块身份的身份证。改了会导致所有引用它的下游项目 go get 失败，且无法自动修复。
