9、Git标签管理：语义化版本控制、git tag（轻量标签与附注标签）、git describe
说到版本控制，很多人第一反应是「分支管理」。但我觉得，标签（Tag）才是真正意义上的里程碑。分支是流动的，今天在 dev 上，明天可能就合并到 main 了。但标签不一样——它钉死一个历史节点，永远不会变。
我刚开始带团队的时候，大家发版全靠口头约定：「诶，那个版本号是 v1.2.3 对吧？」结果每次排查问题都要翻半天日志。后来我强制要求：所有发布必须打标签。从那以后，线上回滚、版本追溯，效率翻了好几倍。
这一章，我们就来聊聊 Git 标签怎么用、怎么管，以及语义化版本号到底该怎么定。
9.1 语义化版本控制（SemVer）
先说说版本号。你肯定见过 v1.2.3 这种格式，但你知道每个数字代表什么吗？
语义化版本控制（Semantic Versioning，简称 SemVer）定义了一套标准：
| 格式 | 示例 | 含义 |
|---|---|---|
主版本号.次版本号.修订号 |
2.5.1 |
主版本：不兼容的 API 修改 次版本：向下兼容的功能新增 修订号：向下兼容的问题修复 |
| 预发布版本 | 2.5.1-alpha.1 |
在正式版本前加 -alpha、-beta、-rc 等 |
| 构建元数据 | 2.5.1+build.20240301 |
用 + 号附加构建信息，不影响版本优先级 |
举个例子：v3.0.0-beta.2 表示第三个大版本的第二个 Beta 测试版。一旦正式发布，就变成 v3.0.0。
9.2 Git 标签：轻量标签与附注标签
Git 提供了两种标签：轻量标签和附注标签。很多人一开始只用轻量标签，觉得方便。但我建议你：正式发布一定要用附注标签。
为什么？我们来看区别。
9.2.1 轻量标签（Lightweight Tag）
轻量标签就是一个指向某个提交的指针。说白了，它就是一个「书签」。创建方式很简单：
git tag v1.0.0这样就在当前提交上打了一个 v1.0.0 的标签。它不包含任何额外信息——没有作者、没有日期、没有备注。你只能看到它指向哪个 commit。
轻量标签适合什么场景？我个人觉得，临时标记、内部测试、个人开发用轻量标签就够了。比如你正在调试一个功能，想记住某个中间状态，打个轻量标签很方便。
9.2.2 附注标签（Annotated Tag）
附注标签就正式多了。它像一次完整的提交：有作者信息、有日期、有备注，甚至可以用 GPG 签名。创建方式：
git tag -a v1.0.0 -m "正式发布 v1.0.0 版本，包含用户登录模块"用 -a 表示附注标签，-m 后面写备注。如果你不写 -m，Git 会打开编辑器让你输入。
查看附注标签的详细信息：
git show v1.0.0你会看到类似这样的输出：
tag v1.0.0
Tagger: 张三 <zhangsan@example.com>
Date: Mon Mar 1 10:00:00 2024 +0800
正式发布 v1.0.0 版本，包含用户登录模块
commit abc123def456...
Author: 李四 <lisi@example.com>
Date: Mon Mar 1 09:55:00 2024 +0800
feat: 完成用户登录功能v2.1.0，结果发现那个标签指向的 commit 根本不是发布时的代码——因为有人后来在同一个分支上 rebase 了。轻量标签不会记录创建时间，你根本不知道它是什么时候打的。从那以后，所有正式发布我强制要求用附注标签。
9.2.3 标签的常用操作
列出所有标签：
git tag
git tag -l "v2.*" # 支持通配符过滤给历史提交打标签：
git tag -a v1.0.0 abc123def -m "补打标签"删除标签：
git tag -d v1.0.0 # 删除本地标签推送标签到远程：
git push origin v1.0.0 # 推送单个标签
git push origin --tags # 推送所有未推送的标签删除远程标签：
git push origin --delete v1.0.09.3 git describe：自动生成可读版本描述
你有没有遇到过这种情况：线上出了 bug，你拿到一个 commit hash，比如 a1b2c3d4，然后你根本不知道这个 commit 对应哪个版本？
git describe 就是解决这个问题的。它能根据最近的标签，自动生成一个可读的描述字符串。
用法很简单：
git describe
# 输出示例：v1.0.0-5-gabc1234这个字符串的含义：
v1.0.0：最近的标签5：从该标签之后，又提交了 5 次gabc1234：当前 commit 的缩写 hash（前面的g表示 Git）
如果你在标签所在的 commit 上运行：
git describe
# 输出：v1.0.0直接返回标签名，干净利落。
还可以指定标签匹配模式：
git describe --match "v*" --abbrev=7这个命令在 CI/CD 中特别有用。我通常会在构建脚本里这样用：
VERSION=$(git describe --tags --always)
echo "当前版本: $VERSION"
docker build -t myapp:$VERSION .这样每次构建的镜像都带有一个可追溯的版本号，线上排查问题直接看镜像标签就知道对应哪个代码版本。
git describe 会报错。加上 --always 参数，它就会直接返回 commit hash，保证不会空手而归。
9.4 标签管理的最佳实践
说了这么多，总结几条我这些年积累下来的经验：
- 正式发布用附注标签，轻量标签只用于临时标记。
- 标签名遵循语义化版本，比如
v2.1.0，不要用v2.1或release-2.1.0这种不统一的格式。 - 标签一旦推送，不要删除。如果版本发错了，可以打一个新标签，比如
v2.1.1，而不是删掉v2.1.0重新打。因为别人可能已经依赖了那个标签。 - 在 CI/CD 中集成
git describe，让每个构建产物都能追溯到代码版本。 - 标签和分支分开管理。不要在分支名上用
v1.0.0这种格式，容易和标签混淆。
嗯，标签管理看似简单，但用好了真的能省很多事。你想想看，一个团队几十个人，每天提交几百次，如果没有标签，你怎么知道哪个版本是稳定的？哪个版本是线上正在跑的？
说白了，标签就是你的「版本锚点」。打好标签，回滚不慌，排查不愁。
公众号:蓝海资料掘金营，微信deep3321