Go Modules实操关键在于模块路径、版本解析规则、代理与校验策略三者对齐：module路径须匹配import路径且小写；go.sum校验失败多因GOPROXY与GOSUMDB配置冲突；MVS算法默认选最低兼容版本，升级需go mod tidy重计算。
Go Modules 不是“学完就懂”的概念，而是用错一次就会卡住编译或拉不到私有库的实操机制。它没有魔法，只有三件事必须对齐：模块路径、版本解析规则、代理与校验策略。其他都是这三者的展开。
go mod init 时 module 路径写错，后续所有依赖都可能失效
module 路径不是项目文件夹名，而是将来别人 import 你包时用的完整导入路径。比如你的 GitHub 仓库是 github.com/yourname/myapp，那初始化就必须写：
go mod init github.com/yourname/myapp
如果随手写成 go mod init myapp，后续别人 import 时用 github.com/yourname/myapp，Go 就会认为这是两个不同模块，导致重复引入、类型不兼容甚至 cannot load 错误。
- 路径中不能含大写字母（Go 官方规范强制小写）
- 本地开发时路径可临时设为
example.com/myapp，但上线前必须和代码托管地址一致 - 已有
import语句的项目，go mod init后建议立刻跑go build，看是否报import path not found
go.sum 校验失败常见于 GOPROXY 或 GOSUMDB 配置冲突
go.sum 不是可选文件，它是 Go 构建时默认校验的依据。一旦出现 checksum mismatch，90% 是因为：
立即学习“go语言免费学习笔记（深入）”；
- GOPROXY 设置了国内镜像（如
https://goproxy.cn），但GOSUMDB仍用默认的sum.golang.org，而镜像源返回的哈希与官方不一致 - 私有模块被错误地走代理（没配
GOPRIVATE），导致拉取到篡改过的包 - 手动编辑过
go.sum，或多人协作时有人删了某行又没运行go mod tidy
解决方法不是删 go.sum，而是对齐策略：
go env -w GOPROXY=https://goproxy.cn,direct<br>go env -w GOSUMDB=off # 仅限内网无校验需求场景<br>go env -w GOPRIVATE=git.internal.company.com
依赖升级后行为异常，大概率是 MVS（最小版本选择）在暗中生效
Go 不按“最新版”选依赖，而是用 MVS 算法找满足所有 require 约束的最低兼容版本。比如你显式 go get github.com/sirupsen/logrus@v1.9.0，但项目里另一个依赖要求 logrus v1.8.0，最终锁定的仍是 v1.8.0 —— 这就是为什么升级后没生效。
- 查真实版本用
go list -m github.com/sirupsen/logrus，不是看go.mod里写的 - 强制升到某版：先
go get github.com/sirupsen/logrus@v1.9.0，再go mod tidy触发重计算 - 想跳过 MVS 强制指定，只能用
replace（慎用，破坏可重现性）：replace github.com/sirupsen/logrus => github.com/sirupsen/logrus v1.9.0
私有模块拉取失败，核心在 GOPRIVATE + git 配置双生效
只设 GOPRIVATE=git.example.com 不够。Go 会跳过代理，但还得让 git 自己能连上私有地址。常见断点：
- git URL 是
ssh://git@git.example.com/xxx/yyy.git，但本地没配置 ssh key 或~/.gitconfig缺少 credential helper - 用 HTTPS 地址但没配 git 凭据缓存，每次拉取都卡在用户名密码提示
- 公司 GitLab 启用了子组嵌套（如
git.example.com/group/subgroup/project），GOPRIVATE必须写全前缀：GOPRIVATE=git.example.com/group/subgroup
验证方式很简单：在终端直接 git ls-remote https://git.example.com/xxx/yyy.git，能通才说明 Git 层没问题。
真正难缠的是 go.sum 里混进了私有模块的哈希，但 GOPRIVATE 没覆盖全——这种问题不会报错，只会让 CI 环境构建失败，且难以复现。
