Go Modules 是 Go 1.11 引入、1.16 起默认启用的官方依赖管理机制；需用 go mod init 初始化，go mod tidy 同步依赖，go get 精确控制版本，依赖校验由 go.mod 和 go.sum 共同保障。
Go Modules 是 Go 1.11 引入的官方依赖管理机制，从 Go 1.16 开始默认启用——如果你还在用 GO111MODULE=off 或手动维护 vendor/，大概率会遇到版本不一致、go get 行为异常、CI 构建失败等问题。
初始化项目时如何正确启用 Go Modules
在项目根目录执行 go mod init 即可启用。模块名通常为 Git 远程地址（如 github.com/username/project），但不是必须与远程仓库一致；它只用于标识该模块在 import 语句中的前缀。
- 如果当前目录已有
go.mod，重复执行go mod init会报错，需先删掉再重试 - 模块名若省略（即
go mod init不带参数），Go 会尝试从当前路径推导，但容易出错，尤其路径含空格或非 ASCII 字符时 - 初始化后立即运行
go mod tidy，能补全缺失依赖并清理未使用的项，比单纯go build更可靠
添加/升级依赖时为什么 go get 不按预期工作
go get 的行为取决于是否带版本后缀、是否在 go.mod 中已存在该模块，以及 GO111MODULE 环境变量状态（即使 Go ≥1.16，设为 off 仍会退化为 GOPATH 模式）。
- 加版本：例如
go get github.com/sirupsen/logrus@v1.9.3，会精确写入go.mod并下载对应 commit - 不加版本：如
go get github.com/sirupsen/logrus，默认拉取 latest tag（或主分支最新 commit），但可能跳过预发布版本（如v2.0.0-rc1） - 升级到最新 minor：用
go get -u；升级到最新 patch：用go get -u=patch；二者都可能引入破坏性变更，慎用于生产依赖 - 若
go get提示 “found meta tag … in …”，说明 Go 尝试走 GOPATH 模式解析，检查是否误设了GO111MODULE=off或当前不在模块根目录
go.mod 和 go.sum 文件分别管什么
go.mod 记录模块路径、Go 版本声明、直接依赖及其版本；go.sum 是所有依赖（含间接依赖）的校验和快照，用于保证构建可重现。
立即学习“go语言免费学习笔记（深入）”；
- 不要手动编辑
go.sum，它由go mod download、go build等命令自动更新 - 若
go.sum报校验失败（如 “checksum mismatch”），常见原因是本地缓存损坏或代理篡改，可运行go clean -modcache清理后重试 -
go mod verify可单独校验go.sum是否与当前依赖树匹配，适合 CI 中做完整性检查 - 私有模块若使用 SSH 地址（如
git@github.com:org/repo），需确保git命令能正常 clone，否则go mod download会卡住或报错
私有仓库和替换依赖的实用配置
当依赖指向公司内网 GitLab、或需要临时调试 fork 分支时，得靠 replace 和 exclude 控制依赖解析逻辑。
- 本地调试：在
go.mod末尾加replace github.com/orig/lib => ./local-fork，路径支持相对路径或绝对路径 - 私有模块：设置
GOPRIVATE=git.company.com/*，让 Go 跳过对这些域名的 checksum 检查和公共代理转发 - 替换为 HTTPS：若 SSH 不通，可用
replace old.org/x => https://git.company.com/old/x，但需确保该 URL 可被git clone访问 -
exclude仅用于屏蔽特定版本（如已知崩溃的v1.2.3），不能解决兼容性问题，慎用；优先考虑replace或升级上游
真正麻烦的往往不是配置本身，而是团队成员本地环境不一致（比如有人开了 GO111MODULE=auto 却在 GOPATH 下操作）、CI 使用旧版 Go、或私有模块权限未同步到构建机——这些细节比语法更常导致构建失败。
