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语言免费学习笔记（深入）”；
iWebShop基于iWebSI框架开发，在获得iWebSI技术平台库支持的条件下，iWebShop可以轻松满足用户量级百万至千万级的大型电子商务网站的性能要求。站点的集群与分布式技术（分布式计算与存储/高可用性/负载均衡）被屏蔽在SI 平台之内，基于iWebShop并且按照SI平台库扩展规范开发的新增功能模块，也将同时获得这种超级计算与处理的能力。作为开源的LAMP电子商务系统，iWebShop
- 本地
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 生态里能用
go get 能否真正拉到、能否编译通过。这个 gap 一出，补救成本远高于多花两分钟本地测一次。 
