go.mod 中 module 声明必须与 import 路径及实际仓库路径完全一致，否则会导致 checksum mismatch、ci 构建失败或他人无法正确引入；replace 仅用于本地依赖重定向且目标须含 go.mod；import 别名仅解决同名符号冲突，不改变模块路径解析。
go.mod 中 module 声明必须和 import 路径完全一致
模块路径不是别名，而是 Go 依赖解析的唯一依据。如果你在 GitHub 上托管代码于 github.com/yourname/myapp，那么 go.mod 第一行必须是 module github.com/yourname/myapp。写成 module myapp 或 module ./myapp 看似能本地编译，但会导致：
• 其他人 go get github.com/yourname/myapp 后 checksum 校验失败（verifying ...: checksum mismatch）
• CI 构建时因 GOPROXY 缓存校验不通过而中断
• 私有 GitLab 仓库若路径含子组（如 gitlab.com/group/subgroup/repo），漏掉 subgroup 就会触发同样错误
replace 不是路径别名，而是本地模块重定向机制
replace 的作用是临时替换某个依赖模块的源，不是给 import 路径起别名。它只影响当前模块的构建行为，不传播给下游依赖。
• 正确用法：在 go.mod 底部加 replace github.com/you/utils => ../utils，且 ../utils 目录下必须有合法 go.mod
• 错误做法：
– 手动改所有 import 语句指向本地路径（破坏可移植性）
– 在 go.mod 里删掉原 require 再用 go mod edit -replace（易漏掉版本约束）
– 使用 ~/path 或绝对路径（Go 不支持 tilde 展开，会报错 invalid module path）
import 别名解决包名冲突，和模块路径无关
当两个不同路径的包导出同名类型或函数（比如都叫 Client），才需要 import 别名——这和模块路径、replace、go.mod 声明完全无关。
• 示例：同时导入 "github.com/a/client" 和 "github.com/b/client"，可写作：
import (<br> aclient "github.com/a/client"<br> bclient "github.com/b/client"<br>)
• 注意：
aclient 是导入别名，不是模块名；它不改变依赖解析路径，也不影响 go.sum 记录
go mod tidy 不自动修复 module 路径错配
go mod tidy 只负责同步 require 列表与实际 import，它不会检查或修正 module 行是否匹配真实仓库地址。
• 常见误判：运行 go mod tidy 后没报错，就以为路径没问题——其实只是本地缓存掩盖了问题
• 验证方法：
– 删除 $GOPATH/pkg/mod/cache 和本地 go.sum
– 在全新环境（如 Docker 容器）中执行 go build，看是否出现 cannot find module providing package
– 检查 go list -m 输出的模块路径是否与 import 语句前缀一致
go.sum、甚至 GOPROXY 的宽松策略都会兜底。只有当别人拉取、CI 构建、或切换 GOPROXY=direct 时，才会突然崩掉。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
