go.mod 中的 module 指令必须严格匹配代码托管的实际仓库路径，否则会导致 checksum mismatch 等依赖校验失败；replace 应使用相对或绝对路径且目标含 go.mod；go get 应优先用语义化版本或 commit hash；goproxy 和 gosumdb 需合理配置以保障依赖安全与可用性。
go.mod 中的 module 指令必须匹配实际仓库路径
Go 模块路径不是随意起的，它直接决定 go get 时如何解析依赖、如何校验 checksum、以及是否能被他人正确引入。如果你的代码托管在 github.com/yourname/project，那么 go.mod 第一行必须是：
module github.com/yourname/project。如果写成
module myproject 或 module project，本地能编译，但别人 go get github.com/yourname/project 后，Go 会按模块路径去查 checksum，发现不匹配，报错 verifying github.com/yourname/project@v0.1.0: checksum mismatch。
常见踩坑点：
- 从已有项目复制
go.mod时没改module行 - 本地开发用
go mod init myapp起名，后续推到 GitHub 却用了不同路径 - 私有 Git 服务（如 GitLab）上路径含子组（
gitlab.com/group/subgroup/repo），漏掉subgroup
替换私有模块或本地调试依赖要用 replace 而非直接改 import 路径
想临时用本地修改的 github.com/you/utils 替代远程 v1.2.0 版本？别改所有 import 语句，也不要在 go.mod 里删掉原依赖再手动 go mod edit -replace——正确做法是在 go.mod 底部加：
replace github.com/you/utils => ../utils或
replace github.com/you/utils => ./local-utils。这样
go build 和 go test 都能生效，且不影响他人拉取时的行为。
注意：
立即学习“go语言免费学习笔记（深入）”；
-
replace只在当前模块生效，不会传播给下游依赖 - 路径必须是绝对路径或相对于当前
go.mod的相对路径，不能是~/path - 如果目标目录没有
go.mod，Go 会尝试读取其go.sum或按 legacy mode 解析，容易出错；建议被 replace 的目录也运行一次go mod init
go get 时版本号写法直接影响依赖解析结果
go get 后跟的版本标识不是“随便写个 tag 就行”。Go 会按规则匹配：优先找 vX.Y.Z 格式的 tag，其次 fallback 到 commit hash，最后才是 branch 名（但 branch 不推荐用于生产依赖）。例如：
go get github.com/sirupsen/logrus@v1.9.3是明确、可复现的；而
go get github.com/sirupsen/logrus@master会导致每次
go mod tidy 都可能拉到不同 commit，go.sum 也会频繁变动。
实用建议：
- 生产环境一律用语义化版本（
vN.N.N）或完整 commit hash（abcdef123） - 避免使用
latest—— 它不是关键字，Go 会当成 branch 名处理，行为不可控 - 如果依赖尚未打 tag，可用
go get github.com/u/p@8a7f2b1锁定具体提交
GO111MODULE=on 是默认行为，但 GOPROXY 和 GOSUMDB 会影响依赖可信度
Go 1.16+ 默认启用模块模式，不需要手动设 GO111MODULE=on。真正影响日常体验的是：GOPROXY（代理源）和 GOSUMDB（校验数据库）。国内直连 proxy.golang.org 常失败，可设：
export GOPROXY=https://goproxy.cn,direct。但注意：
goproxy.cn 不提供 sum.golang.org 的镜像，所以还得保留 GOSUMDB=off 或配成 GOSUMDB=sum.golang.google.cn（需确认该服务是否仍可用）。
关键细节：
-
GOSUMDB=off会跳过校验，适合离线开发，但上线前务必关掉 -
GOPROXY=direct表示绕过代理直连，若网络不通就会卡住；推荐用逗号分隔多个源，如https://goproxy.cn,https://proxy.golang.org,direct - 私有模块若走 SSH（
git@github.com:org/repo.git），需确保GOPROXY不强制代理，否则会因协议不匹配失败
go env 输出和 go.mod 文件结构，比反复 go clean -modcache 有用得多。 
