Go modules 必须开启 GO111MODULE=on，否则依赖无法版本锁定、不生成 go.mod/go.sum，且 Go 1.16+ 在无 go.mod 时可能回退至 legacy 模式。
Go modules 为什么必须开启 GO111MODULE=on
不启用模块模式时，go get 会直接写入 $GOPATH/src，无法锁定依赖版本，也无法生成 go.mod 和 go.sum。即使项目在 $GOPATH 外，只要环境变量未显式设为 on，Go 1.16+ 仍可能 fallback 到 legacy 模式（尤其当目录下无 go.mod 且存在 GOPATH 路径匹配时）。
实操建议：
- 全局设置：
go env -w GO111MODULE=on - CI/CD 中务必显式声明：
GO111MODULE=on go build，避免因 Docker 基础镜像或系统默认值导致行为不一致 - 若需临时禁用（极少见），用
GO111MODULE=off go list -m all，但此时所有go mod子命令均不可用
如何正确打语义化标签并同步到 go.mod
Go 不从 Git 标签自动推导模块版本；go mod tidy 或 go get 也不会自动拉取最新 tag —— 它只认 go.mod 里声明的 require 版本。想让下游使用你的新版本，必须手动更新并提交 go.mod。
标准流程：
立即学习“go语言免费学习笔记（深入）”；
- 先提交代码并确保通过测试：
git add . && git commit -m "feat: add retry logic" - 打符合语义化规范的 tag：
git tag v1.2.0（注意：不能是1.2.0或release/v1.2.0） - 推送 tag：
git push origin v1.2.0 - 下游使用时，显式指定版本：
go get example.com/mylib@v1.2.0，该操作会更新其go.mod中的require行并触发go.sum更新
replace 和 exclude 在版本管理中该怎么用
replace 是开发期绕过远程版本、指向本地路径或 fork 仓库的临时方案；exclude 则用于彻底屏蔽某个版本（如已知有严重安全漏洞且暂无法升级）。二者都只作用于当前 module，不会影响下游。
常见误用场景与建议：
-
replace后未还原就合入主干 → 下游构建失败，因为路径不存在。正确做法：仅保留在develop分支，PR 合并前删掉replace行，并用go get拉正式版 -
exclude不能替代require降级。例如exclude github.com/some/lib v1.5.0并不会让 Go 选v1.4.0，它只是禁止解析出v1.5.0—— 若其他依赖强制要求该版本，仍会报错 - 调试多模块协作时，可用
replace指向本地 sibling 目录：replace example.com/other => ../other，但路径必须是相对当前go.mod的有效文件系统路径
go list -m -versions 输出为空或不全怎么办
go list -m -versions some/module 依赖 proxy（默认 proxy.golang.org）和源站 tag 可发现性。常见原因包括：模块未发布公开 tag、tag 名称不符合 vX.Y.Z 格式、源站未启用 Go module proxy 支持，或网络策略拦截了 proxy 请求。
排查步骤：
- 确认远端有合规 tag：
git ls-remote --tags origin | grep '^.*[[:digit:]]\+\.[[:digit:]]\+\.[[:digit:]]\+$' - 绕过 proxy 查看原始源：
GOPROXY=direct go list -m -versions some/module（需确保该模块支持/@v/list端点） - 若使用私有仓库，必须配置
GOPROXY指向内部 proxy（如 Athens）或用replace+exclude组合替代 - 注意：该命令不显示本地未推送的 tag，也不显示 pre-release 版本（如
v2.0.0-beta.1），除非显式请求：go list -m -versions some/module@v2.0.0-beta.1
真正麻烦的是混合使用 replace、私有 proxy 和 fork 分支的场景 —— 此时 go mod graph 和 go list -m all 的输出容易产生歧义，建议每次发版前用干净环境（rm -rf $(go env GOPATH)/pkg/mod/cache）验证依赖解析结果。
