go模块版本管理必须严格遵循semver规范，即vx.y.z格式，主版本≥2时需在module path和import路径中添加/vn后缀，且tag必须带v前缀，否则被视作伪版本导致依赖不可控。
公共模块版本号必须严格遵循 SemVer 规范
Go 的 go mod 依赖解析完全依赖语义化版本（SemVer），任何偏离 vX.Y.Z 格式的 tag（比如 1.2.3、release-1.2、master）都会被 Go 视为“预发布版本”，无法参与最小版本选择（MVS）算法，导致下游项目无法稳定升级或降级。
常见错误现象：本地打 tag 用 git tag 1.2.0，结果 go get example.com/lib@1.2.0 报错 no matching versions；或 go list -m -versions 列不出该版本。
- 正确做法：所有 release tag 必须带
v前缀，如v1.2.0、v2.0.0 - 主版本升级（
v2+）必须变更模块路径，例如从example.com/lib→example.com/lib/v2，否则 Go 不识别为独立模块 - 避免使用
@latest或分支名（如@main）作为生产依赖，它们不触发go.sum校验，破坏可重现构建
主版本迭代必须同步更新模块路径和 import 路径
Go 不支持同一模块路径下的主版本共存。当你需要引入不兼容变更（如函数签名删除、结构体字段移除），不能只改 tag，必须显式分拆模块路径。
错误示例：go.mod 中写 require example.com/lib v2.0.0，但模块路径仍是 example.com/lib —— 这会导致 go build 失败，报 module example.com/lib@v2.0.0 is not compatible with the current module。
- 步骤一：在公共模块仓库中，将
go.mod第一行改为module example.com/lib/v2 - 步骤二：所有导出的包路径（如
example.com/lib/utils）自动变为example.com/lib/v2/utils - 步骤三：下游项目需同步修改 import 语句，并运行
go get example.com/lib/v2@v2.0.0 - 旧版
v1.x仍可继续维护，路径不变，与v2并行存在
小版本和修订版本应按实际变更类型发布，而非按时间或开发节奏
Go 的 MVS 算法默认选“满足约束的最老兼容版本”。如果你把破坏性变更塞进 v1.2.1（本该是 bugfix），下游项目 go mod tidy 后可能意外升级并崩溃；反之，若把纯新增 API 放进 v1.3.0 却标为 v1.2.1，则别人无法通过 @~1.2.0 安全获取新功能。
-
v1.2.0 → v1.2.1：仅修复 bug，不新增导出符号，不修改现有接口行为 -
v1.2.0 → v1.3.0：新增导出函数/方法/字段，且不破坏已有调用（如加参数带默认值不算，Go 不支持） -
v1.2.0 → v2.0.0：任何不兼容变更，包括删除导出项、修改函数签名、改变返回值结构等 - 所有变更必须体现在
go.mod的require块中 —— 如果只是内部重构没动 API，不需要发新版
私有模块或内部 SDK 的版本管理容易忽略校验环节
使用 GOPROXY 或私有代理时，go.sum 文件仍会生成，但若未配置 GOSUMDB=off 或对应私有 sumdb，go build 可能因校验失败中断，尤其在 CI 环境下静默失败。
- 确认私有模块的
go.sum条目是否被信任：执行go mod download -x查看实际下载源和校验过程 - 若使用自建 proxy，确保其返回的
.info和.mod文件与本地 tag 内容一致，否则go mod verify会失败 - 禁止在
go.mod中用replace指向本地路径发布到生产 —— 这会导致go.sum缺失真实哈希，不同机器构建结果不可控
版本不是数字游戏，而是契约。每次 git tag -a v1.2.0 -m "..." 的瞬间，你签下的是一份对所有 import 它的项目的隐式协议：这个版本的行为边界在哪里，谁可以安全升级，谁必须重写代码 —— Go 不会替你检查这点，它只忠实地执行你写的 tag 和路径。
