Git Tag 完全使用指南从打标签到部署冻结的实践

作者：CherryYang 发布时间： 2026-06-15 阅读量：16 评论数：0
使用教程
#git #git tag

Git Tag 完全使用指南:从打标签到部署冻结的实践

核心目的:系统梳理 git tag 的全部常用操作,并解决一个真实场景——如何用 tag 冻结一份不变的代码快照拿去部署,而不被分支后续的开发提交污染。

什么是 Git Tag

Tag(标签)是 Git 给某个 commit 起的一个固定的、人类可读的名字。可以把它理解为给历史长河里的某个时间点钉上一根桩——v1.0.0 永远指向你打标签那一刻的那个 commit。

关键在于对比 branch(分支):

  • branch 是会移动的指针。你每次在 dev 上提交,dev 这个指针就往前走一格,始终指向该分支的最新 commit。
  • tag 是不会移动的指针。一旦打在某个 commit 上,它就钉死在那里,之后这个分支怎么开发都跟它无关。

这个"不可变"的特性,正是 tag 最核心的价值。需要一份"无论什么时候拉取都长得一模一样"的代码时,tag 就是标准答案。

背景与目标

典型的开发模型:master 分支用于线上部署,dev 分支用于开发新功能。现在要在内网部署一个内测版本,想用 dev 当前的代码,但有个硬性要求——部署机后续拉取代码时,不能把 dev 上正在开发的半成品也带进来。

如果直接让部署机跟踪 dev 分支,每次 git pull 都会拉到 dev 的最新提交,内测版就会混入一堆没测完的功能。解决办法就是在 dev 当前节点打一个 tag,让部署机切到这个 tag 上——代码从此冻结。

完成本文后,你会掌握 tag 的创建、推送、查看、切换、修改、删除全套操作,以及几个容易踩的坑。

两种 Tag:lightweight 与 annotated

Git 的 tag 分两种,先分清:

# 轻量标签 (lightweight):只是一个指向 commit 的指针,不存任何额外信息
git tag v1.0.0

# 附注标签 (annotated):作为完整对象存入 Git 数据库,
# 带有打标签人、邮箱、日期、说明信息,还可以 GPG 签名
git tag -a v1.0.0 -m "内网内测版本"

二者的区别不只是"有没有说明":annotated tag 是 Git 对象库里一个独立的对象,记录了"谁在什么时候为什么打的"这些元数据;lightweight tag 只是一个名字而已。

⚠️ 发布、部署相关的 tag 一律用 annotated(-a)。git describe、CI/CD 等工具都依赖 annotated tag 的元数据,用 lightweight 会出现行为异常。lightweight 只适合自己临时打的本地书签。

创建 Tag

基本命令与参数

默认 git tag 打在当前 HEAD 所在的 commit 上:

git tag -a v1.0.0 -m "版本说明"

常用参数含义:

  • -a:annotated,创建附注标签
  • -m "<msg>":指定说明信息(给了 -m 会自动按 -a 处理)
  • -s:signed,用 GPG 签名(团队有签名规范时使用)
  • -f:force,强制覆盖已存在的同名 tag(危险操作,见后文)

给指定 commit 打 Tag

如果要给某个历史 commit 而非当前 HEAD 打标签,把 commit hash 接在命令最后即可:

git tag -a v1.0.0 9fceb02 -m "针对这个历史 commit 打 tag"

hash 写前 7 位左右、能唯一定位即可,不必写全。

推送 Tag

git push 默认不会把 tag 推送到远端,必须显式推:

# 推送单个 tag
git push origin v1.0.0

# 推送所有本地尚未推送的 tag(含 lightweight,慎用)
git push origin --tags

# 推荐:只推送「能从已推送 commit 追溯到」的 annotated tag
git push --follow-tags

--tags 会把所有本地 tag 一股脑推上去,包括你随手打的 lightweight 标签;--follow-tags 更克制,日常更推荐。

查看 Tag

git tag                      # 列出所有 tag
git tag -l "v1.*"            # 按通配符过滤
git tag -n                   # 列出 tag 的同时显示说明信息
git tag --sort=-creatordate  # 按创建时间倒序(最新的在最上面)

git show v1.0.0              # 查看某个 tag 的详细信息及其指向的 commit

切换到 Tag 与 detached HEAD

把部署机的代码切到某个 tag:

git fetch --tags     # 先把远端 tag 拉到本地
git checkout v1.1    # 切到 tag,等价的新语法是 git switch --detach v1.1

切过去之后会看到这样一段提示:

Note: switching to 'v1.1'.
You are in 'detached HEAD' state. ...
HEAD is now at a8954f85 添加.idea到gitignore

这不是错误,而是进入了 detached HEAD(分离头指针) 状态。平时在分支上时,HEAD 指向的是分支名(如 dev);现在它"脱离"了分支,直接钉在 v1.1 对应的那个 commit 上。

这正是部署冻结快照想要的状态:你不在任何分支上,代码稳稳停在 v1.1,dev 后续怎么开发都不会影响它。

如果切过去后还想基于这个版本继续提交(比如要在内测版上单独打补丁),则需要新建一个分支来承载提交——因为 detached HEAD 状态下的提交不属于任何分支,切走后会被 Git 当垃圾回收:

git switch -c hotfix-beta   # 等价于 git checkout -b hotfix-beta

修改与删除 Tag

修改:本质是删除重建

Git 的 tag 设计上是不可变的,没有真正意义上的"修改"操作。所谓修改,本质都是删除后重建或强制覆盖。

# 改 tag 的说明信息:重新用 -f 打一遍(默认仍指向原 commit)
git tag -f -a v1.0.0 -m "修改后的说明"

# 改 tag 指向的 commit:强制重打到新 commit
git tag -f -a v1.0.0 <new-commit> -m "说明"

# 重命名:没有 rename 命令,只能新建 + 删旧
git tag new-name old-name    # 用旧 tag 创建新 tag(指向同一 commit)
git tag -d old-name          # 删除旧 tag

删除

git tag -d v1.0.0                  # 删除本地 tag
git push origin --delete v1.0.0    # 删除远端 tag

⚠️ 上面这些操作只改了本地。如果 tag 已经推到远端,要让远端也更新,必须强推(git push -f origin v1.0.0)。但只要 tag 已经共享出去、可能被别的环境用过,就尽量别改——原因见下一节的踩坑记录。

经典使用场景

版本发布(release):给正式版本打 tag(v2.3.0),配合代码托管平台从 tag 生成 Release 页面和压缩包下载。这是 tag 最主流的用途。

部署快照冻结:也就是本文的主场景。从 dev 当前节点打 tag,部署机 checkout 到该 tag,得到一份不随分支移动的稳定快照。

回滚到历史版本:线上出问题需要回退时,直接 checkout 到上一个稳定 tag(git checkout v2.2.0)重新部署,精确且快速。

CI/CD 触发:很多流水线配置成"push 带特定格式的 tag 时自动触发构建和发布"。开发者只需 git push origin v1.0.0,后续打包、镜像构建、部署全自动完成。

生成构建版本号:git describe --tags 能基于最近的 tag 描述当前 commit,常用于在构建产物里嵌入版本信息:

git describe --tags
# 输出形如:v1.0.0-beta.1-3-g9fceb02
# 含义:最近的 tag 是 v1.0.0-beta.1,之后又有 3 个 commit,
#       当前 commit 的短 hash 是 9fceb02

预发布版本管理:用 SemVer(语义化版本)的预发布后缀区分内测、候选发布等阶段:

v1.4.2           正式版    vMAJOR.MINOR.PATCH
v1.5.0-beta.1    内测版
v1.5.0-rc.1      候选发布  release candidate

踩坑记录:那些对 Tag 的常见误解

这一节记录在实践中真实出现过的几个误解,基本都源于"把 tag 当成分支来理解"。

误解一:想把 tag「移动」到最新 commit

场景:某个版本上线后发现有东西没改掉,于是想"把这个 tag 移动到修复后的最新 commit 上,再用同一个 tag 发布"。

为什么是坑:tag 在设计上就是不可变的命名快照,不是会移动的分支。移动一个已经发布的 tag,会导致"同名 tag 在不同机器上指向不同 commit"的诡异状态——已经拉取过旧 tag 的部署机,默认不会自动更新成新指向,排查起来极其折磨。

正确做法:不要移动已发布的 tag,而是打一个新版本号。

# 推荐:提交修复后,打新版本号(而不是动旧 tag)
git commit -m "fix: 修复 xxx"
git tag -a v1.1.1 -m "修复 xxx 的内测版"
git push origin v1.1.1

# 部署机拉新 tag 并切过去
git fetch --tags
git checkout v1.1.1

每一轮内测都用递增的版本号(v1.1.0-beta.1、v1.1.0-beta.2……),这样每个快照独立、不可变,bug 复现和回归对比才有据可依。

误解二:以为切到 tag 后 git pull 会更新代码

疑问:把部署机切到 v1.1 之后,如果手贱跑了 git pull,会不会把 dev 的新提交拉进来?

真相:不会,有两层保护。其一,tag 本身永远不动,dev 怎么提交都跟它无关;其二,detached HEAD 状态下没有 upstream(上游跟踪分支),裸 git pull 会报类似 You are not currently on a branch 的提示,什么都不做。

⚠️ 唯一的例外:如果你显式执行 git pull origin dev,那确实会把 dev 的提交合并进当前位置。所以部署时根本不需要 pull,别手动去 pull dev。

误解三:以为可以直接「修改」一个 tag

如前文所述,Git 没有原地修改 tag 的能力。任何"修改"都是删除重建或 -f 强制覆盖。理解这一点,就不会指望有什么 git tag --edit 之类的命令。

误解四:以为 git fetch --tags 会自动更新本地已有的同名 tag

场景:远端把 v1.1 强推到了新 commit,部署机执行 git fetch --tags,却发现本地 v1.1 还是旧的。

原因:git fetch 默认不会覆盖本地已存在的同名 tag,即使远端的指向已经变了(新版本 Git 会给个警告但不覆盖)。必须加 --force:

# 部署机上,强制更新本地 tag 到远端的新指向
git fetch --tags --force
git checkout v1.1          # 重新 checkout,HEAD 才会跟到新 commit

如果忘了 --force,部署机会"以为自己已经是 v1.1 了",实际拉的还是没修复的老代码——这种本地与远端不一致的状态非常难排查。当然,只要遵守"误解一"里的建议(打新版本号而非移动 tag),就根本碰不到这个坑。

总结

把 tag 当成会移动的分支来用:

  1. 上线后发现问题,想直接移动 tag 到新 commit
  2. 强推覆盖远端 tag,以为所有环境会自动同步
  3. 结果:同名 tag 在不同机器指向不同 commit,版本对应关系彻底乱套

把 tag 当成不可变快照来用:

  1. 每个版本打一个唯一的、递增的 tag,从不移动
  2. 部署机 checkout 到 tag,进入 detached HEAD,代码自然冻结
  3. 结果:任何时候、任何机器拉取同一个 tag,代码绝对一致

Git Tag 的本质:它是给某个 commit 起的一个不可变的命名快照。最佳实践就一条——版本号只增不改,永远不要移动已经发布出去的 tag。

上一篇：X-Macro
下一篇：并发下锁的初始化问题

评论