Git标签必须严格匹配SemVer（如v1.2.3、v2.0.0）并对应go.mod路径（v1隐含/v1，v2需显式/module github.com/user/repo/v2），分支不参与版本解析，仅用于开发隔离；API不兼容变更须同步更新路径与tag。
Git 标签和分支本身不直接管理 Go 的 API 版本，Go 的 API 兼容性由模块路径（module 声明）和语义化版本号共同约束。自动化管理的关键在于：用 Git 标签承载 SemVer 版本号，用分支控制发布节奏，并通过 go.mod 路径显式声明主版本变更。
Git tag 必须严格匹配 SemVer 并用于 go.mod 版本号
Go 模块的版本解析完全依赖 tag 名称，不是“任意带 v 的字符串”都有效。tag 必须是合法 SemVer（如 v1.2.3、v2.0.0），且需与 go.mod 中的模块路径一致：
-
v1.2.3对应module github.com/user/repo（隐含/v1） -
v2.0.0必须对应module github.com/user/repo/v2，否则 Go 工具会拒绝识别为 v2 版本 - tag 不能带前缀或后缀（如
release-v1.2.3或v1.2.3-rc1不被 Go 模块系统认可，除非是预发布格式v1.2.3-rc.1） - 打 tag 后必须执行
git push origin v1.2.3，仅本地 tag 不会被go get发现
分支只用于开发隔离，不参与 Go 模块版本解析
Go 工具链（go list、go get）根本不读取分支名。分支的作用仅限于团队协作流程，比如：
-
main分支：只允许合并已打 tag 的稳定提交，CI 可校验git describe --tags --exact-match是否成功 -
develop或next分支：集成新功能，但其上的go get github.com/user/repo@develop是浮动引用，构建不可重现，严禁在生产依赖中使用 - 功能分支（如
feature/auth）：不应出现在go.mod的require行中；调试时可用@a1b2c3d提交哈希，而非分支名
API 不兼容变更必须改 go.mod 路径 + 新 tag
当你需要引入破坏性变更（如删除导出函数、修改结构体字段类型），不能只打 v2.0.0 tag —— 还必须同步更新 go.mod 文件中的模块路径：
Pilot Digital Twin Setup
下载
部署一个包含 4 个智能体（agent）的数字孪生平台。在以下情况下使用该技能： 1. 用户希望为物理资产监控与预测性维护等场景搭建数字孪生系统……
立即学习“go语言免费学习笔记（深入）”；
- 旧版路径：
module github.com/user/repo→ 对应v1.x.xtag - 新版路径：
module github.com/user/repo/v2→ 对应v2.0.0tag，且所有导入语句需改为import "github.com/user/repo/v2" - 若跳过路径修改，即使打了
v2.0.0tag，Go 仍将其视为v1系列的伪版本（如v0.0.0-20261010173400-a1b2c3d），无法享受模块隔离
CI 中自动提取版本号并注入二进制
发布时常用 -ldflags 将 Git 版本信息编译进二进制，但注意来源可靠性：
- 推荐方式：
git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0-dev"，它返回最近轻量 tag（如v1.2.3），不依赖注解 tag - 避免
git rev-parse --short HEAD单独使用——它不体现 SemVer，无法表达兼容性含义 - 在 Makefile 或 CI 脚本中组合：
VERSION=$$(git describe --tags --abbrev=0 2>/dev/null || echo "dev"); go build -ldflags "-X main.version=$$VERSION" - Go 程序内可通过
var version = "dev"和init()函数读取，但该值仅作展示，不参与模块版本决策
最易被忽略的一点：Git tag 和 go.mod 路径的耦合是硬性规则，不是约定。哪怕所有文档都说“我们用 v2 tag 表示大改”，只要路径没改成 /v2，Go 就不会把它当 v2 模块加载——这点在跨团队协作或私有 registry 场景下极易出错。
