17370845950

Go模块发布依赖Git标签+v前缀+远程推送，主版本升级需同步修改go.mod路径，发布前须执行go mod tidy和go test ./...确保依赖纯净与全路径测试通过。

go mod 发布不是上传到某个中心仓库，而是靠 Git 标签 + 公开仓库 + Go 工具链自动发现——只要你的代码能被 go get 拉下来，它就是“已发布”。

怎么打 tag 才算真正发布？

Go 模块版本完全依赖 Git 的 vX.Y.Z 标签，没有标签＝没有可引用的版本。

• 必须带 v 前缀：git tag v1.0.0 ✅，git tag 1.0.0 ❌（go get 会忽略）
• 标签必须推送到远程：git push origin v1.0.0，只本地打 tag 没用
• 主版本升级（如 v1 → v2）必须同步改 go.mod 中的模块路径，例如从 github.com/user/lib 改为 github.com/user/lib/v2，否则 Go 认为是两个无关模块
• 预发布标签（如 v2.0.0-rc.1）能被识别，但 go get 默认不选它，需显式指定版本

为什么 go mod tidy 和 go test ./... 是发布前必做？

它们不是仪式，而是防止下游用户“第一秒就失败”的守门操作。

• go mod tidy 清理 go.mod 中残留的未使用依赖，避免用户 go get 时拉取一堆无关包，甚至触发私有域名解析失败
• go test ./... 要跑全路径（注意 ...），因为子目录可能含独立测试；漏掉某个 pkg/xxx 的测试，上线后别人一用就 panic
• 常见错误：只跑 go test（当前目录），结果 examples/ 下的示例代码因依赖变更已无法编译

用户 go get 不到你的

模块？先查这三件事

90% 的“发布失败”其实是路径或可见性问题，和 Go 工具链无关。

• 模块路径是否和仓库地址**完全一致**？比如仓库是 https://github.com/600888/go-dlt645，那 go mod init 必须是 github.com/600888/go-dlt645，少个 go- 或大小写错一个字母都会 404
• 仓库是否公开？私有仓库必须配置 GOPRIVATE，否则 go get 会强制走代理并失败
• 有没有人手动触发过索引？虽然 pkg.go.dev 通常自动抓取，但首次发布建议主动执行：

  GOPROXY=proxy.golang.org go list -m github.com/600888/go-dlt645@v1.0.0

  成功返回才代表全球可用

发布后还能改代码吗？

不能。Go 模块设计上就是「不可变版本」——已发布的 tag 对应的 go.sum 哈希值被硬编码进所有用户的缓存里。

• 如果你强行 git push --force 覆盖旧 tag，其他人的 go build 会直接报校验失败：verifying github.com/xxx@v1.0.0: checksum mismatch
• 修复只能发新版本：v1.0.1，哪怕只是改了个 typo
• 想撤回？唯一办法是发 v1.0.0+incompatible 这类特殊标记（不推荐），或干脆文档里声明该版本废弃

真正的麻烦往往藏在「以为发完了」之后——比如忘记把 examples/ 目录加进 Git，或者 doc.go 缺失导致 pkg.go.dev 上看不到说明。发布不是终点，而是别人开始用你代码的第一秒。