go module tag 必须以 v 开头，否则 go get 无法识别
Go 模块的版本标签不是随便起个 1.2.3 就行的。如果打的是 1.2.3 这种 tag，go list -m -versions 看不到，go get example.com/repo@1.2.3 会报 unknown revision 1.2.3 —— 因为 Go 官方工具链只认 vX.Y.Z 格式（严格匹配语义化版本正则 ^v(0|[1-9]d*).(0|[1-9]d*).(0|[1-9]d*)(?:-((?:0|[1-9]d*|d*[a-zA-Z-][0-9a-zA-Z-]*)(?:.(?:0|[1-9]d*|d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:+([0-9a-zA-Z-]+(?:.[0-9a-zA-Z-]+)*))?$）。
实操建议：
- 打 tag 时必须用
git tag v1.2.3，不是git tag 1.2.3 - 已误打非
v前缀 tag？删掉重打：git tag -d 1.2.3 && git push origin :refs/tags/1.2.3 && git tag v1.2.3 && git push origin v1.2.3 - CI 自动发布脚本里，务必检查
TAG_NAME是否以v开头，否则后续go proxy同步失败
预发布版本（如 v1.2.3-alpha.1）能被 go get 拉取，但默认不参与 go get -u 升级
Go 的模块升级逻辑把预发布版本（含 -alpha、-beta、-rc）视为“不稳定”，所以 go get -u 默认只会升到最新稳定版（即不含连字符的 vX.Y.Z）。但你可以显式指定：go get example.com/repo@v1.2.3-beta.2 是合法的。
常见错误现象：
立即学习“go语言免费学习笔记（深入）”；
- 本地
go.mod里写的是v1.2.3-beta.1，执行go get -u后变成v1.2.3—— 不是 bug，是设计行为 - 想让下游项目“默认用 beta 版”，不能靠 tag 名，得靠
go.mod中replace或文档引导 -
v1.2.3+incompatible不是 tag 问题，而是模块路径未声明go.mod或路径与仓库不一致，和前缀无关
私有模块或非 github 仓库，tag 命名规则不变，但需确保 Git 服务支持语义化解析
gitlab、gitee、自建 gitea 都支持 vX.Y.Z tag，但部分老旧企业 Git 服务（如某些 svn 迁移来的 Git 实例）可能对带 v 前缀的 ref 解析异常。验证方式很简单：git ls-remote origin refs/tags/v* 能列出 tag，且 go list -m -versions example.com/repo 有输出，才算真正就绪。
使用场景注意点：
- 私有模块若用
replace本地开发，tag 名仍要合规，否则上线后go build在 CI 环境会因找不到版本而失败 - 公司内部 Git 服务若禁用
v开头的 ref 推送（少见但存在），需联系运维放开策略，而非妥协用version-1.2.3—— Go 工具链不认 -
go proxy（如 Athens、JFrog）缓存时依赖 tag 名格式，错标会导致所有下游拉不到该版本
打 tag 前没 go mod tidy 或 go build 验证，可能发布一个根本跑不起来的版本
tag 是对某次 commit 的快照，但 Go 模块是否可用，不只看 tag 名，更取决于该 commit 下 go.mod 的完整性、依赖能否 resolve、代码能否编译。曾见过团队打了 v2.0.0，结果 go build 报 missing go.sum entry，因为 go.sum 没提交。
安全操作流：
- 切到目标 commit，运行
go mod tidy && go build ./...，确保无错 - 确认
go.sum已提交（尤其新增依赖后） - 本地试
go get example.com/repo@v2.0.0，看能否成功拉取并go list -m显示正确版本 - 别跳过这步：GitHub/GitLab 页面上看到 tag ≠ Go 生态里能用
事情说清了就结束。最常被忽略的其实是最后一步——打完 tag 就去发公告，忘了验证 go get 能否真正拉到、能否编译通过。这个 gap 一出，补救成本远高于多花两分钟本地测一次。