Git标签必须严格遵循语义化版本vMAJOR.MINOR.PATCH格式（如v1.2.3），Go模块依赖其识别版本；v2+需在go.mod路径中显式包含/v2后缀并同步更新import，否则引发版本错误。
用 git tag 打语义化版本标签，不是随便写个 v1.0 就完事
Go 模块的版本完全依赖 Git 标签，go get、go list -m -versions 全靠它识别可用版本。必须严格遵循 Semantic Versioning 2.0：格式为 vMAJOR.MINOR.PATCH（如 v1.2.3），开头带 v 是硬性要求——没这个 v，Go 工具链直接忽略该标签。
常见错误包括：1.2.3（缺 v）、release-v1.2（非标准格式）、v1.2.3-beta（预发布标签不被 go list 默认显示，需加 -pre 参数才可见）。
- 打正式版：运行
git tag v1.4.0，再git push origin v1.4.0 - 打预发布版（如测试用）：用
git tag v1.4.0-rc1或v1.4.0-beta.2，注意中间用-，不是_或空格 - 标签必须打在对应
go.mod文件已更新模块路径和版本兼容声明（如module example.com/mylib/v2）的提交上
go.mod 中的模块路径要体现主版本号（v2+）
当模块升级到 v2，仅打 v2.0.0 标签远远不够。Go 要求模块路径本身包含主版本后缀，否则所有 v2+ 版本会被视为对 v1 的破坏性覆盖，引发 invalid version 或 unknown revision 错误。
比如原模块是 module github.com/user/pkg，发 v2 时必须改路径为 module github.com/user/pkg/v2，并同步更新所有内部 import 语句——Go 不做自动重写。
立即学习“go语言免费学习笔记（深入）”；
- v1 模块：路径保持
module example.com/lib，标签用v1.5.2 - v2 模块：路径必须为
module example.com/lib/v2，标签用v2.0.0；且go.mod中不能出现replace指向同一仓库的 v1 路径，否则go build会混淆 - 主版本号变更 ≠ 仅改标签名，是模块路径、导入路径、发布流程三者同步变更
验证标签是否生效：别只信 git tag -l
git tag -l 只显示本地标签，而 Go 模块消费者拉取的是远程仓库的标签。必须确认远端已有该 tag，且 go list 能正确解析。
go list -m -versions example.com/mylib/v2
如果返回空或报错 no matching versions，优先检查以下三点：
- 是否执行了
git push origin（不是git push --tags，后者可能推送了不该推的本地测试标签） - 模块仓库是否公开可读（私有仓库需配置 GOPRIVATE 或认证）
- 是否在打了 tag 的 commit 中，
go.mod的module行与 tag 名称语义一致（例如v3.1.0对应module x/y/v3）
小版本和补丁版本的发布节奏，直接影响下游兼容性判断
Go 的 go get 默认只升级 PATCH（如 v1.2.3 → v1.2.4），除非显式指定 @latest 或 @v1.3.0。这意味着你发布的每个 MINOR 版本（如 v1.3.0）都应确保：新增功能向后兼容、不删除导出标识符、不修改函数签名——否则下游 go get -u 会静默引入破坏性变更。
-
PATCH（v1.2.3 → v1.2.4）：只修复 bug，不改 API，可安全自动升级 -
MINOR（v1.2.4 → v1.3.0）：可加新导出函数/字段，但不能删、不能改已有导出项的行为 -
MAJOR（v1.3.0 → v2.0.0）：必须改模块路径，且不保证任何兼容性；下游需主动修改 import 路径
最容易被忽略的是：即使没动代码，只要 go.mod 里 require 的某个依赖升了 MAJOR 版本，你的模块也应升 MAJOR——因为依赖的破坏性变更可能穿透到你的 API 表面。
