正式发布、需审计或触发CI/CD时必须用git tag -a，因其含作者、时间、签名等元数据；轻量标签仅存commit hash，CI系统通常忽略，仅适用于临时本地标记。
什么时候该用 git tag -a 而不是 git tag
正式发布、需要审计或要触发 CI/CD 流水线时，必须用 git tag -a。轻量标签 git tag v1.0.0 只存一个 commit hash，没有作者、时间、签名、消息——CI 系统（比如 GitHub Actions）通常只监听附注标签事件，轻量标签根本不会触发构建。
常见错误现象：打完 v1.2.0 标签后，CI 没反应；查日志发现是轻量标签，git show v1.2.0 输出只有哈希，没有 Tagger: 和 Message: 行。
- 附注标签是独立 Git 对象，可被 GPG 签名，适合交付给客户或上生产
- 轻量标签仅用于临时标记（如“先记下这个修复点”，不对外发布）
- VSCode 命令面板里选 “Git: Create Tag” 默认创建的是轻量标签，容易踩坑
VSCode 里推送标签为什么总失败
因为 VSCode 的「Push」按钮默认只推分支，不推标签——哪怕你刚在终端里执行了 git tag -a，也不代表它会自动同步到远程。
必须显式操作：
- 在集成终端中运行
git push origin v1.2.0（推单个）或git push origin --tags（推全部新增标签） - 在源代码管理侧边栏底部点击「⋯」→「Push Tags」（注意不是「Push」）
- 如果用了 GitLens 插件，右键提交 → 「Tag this commit」→ 勾选「Annotated」→ 创建后仍需手动 Push Tags
容易忽略的点：git push origin --tags 会把所有本地未推送的标签都发上去，包括测试用的 v0.9.0-test，上线前务必先 git tag -d v0.9.0-test 删除。
git push origin --delete v1.1.0 删除远程标签后，本地还能看到吗
能。删除远程标签不影响本地标签存在，git tag 依然列出它。但下次 git fetch 或 git pull 不会把它拉回来——因为远程已无此引用。
典型误操作场景：
- 误推了一个带错版本号的标签（如
v1.10.0实际应为v1.1.0） - 删完远程后忘记删本地：
git tag -d v1.10.0，导致下次--tags又把它推回去 - 团队成员没及时
git fetch --prune，本地还残留已删除的标签，造成混淆
建议流程：删远程 → 立即删本地 → 通知协作者执行 git fetch --prune 清理远端引用缓存。
CI/CD 流水线只认 v* 标签，但开发打了 release/v1.2.0 怎么办
GitHub Actions、GitLab CI 等默认只监听顶层标签，release/v1.2.0 这种带斜杠的路径式标签不会触发 on: push: tags 事件——它被当作文本字符串，不是合法语义化版本标识。
解决方式只有两个：
- 严格按约定命名：用
v1.2.0、v2.0.0-rc1，别加前缀或目录结构 - 改 CI 配置，显式匹配：
tags: ['release/*', 'v*.*.*']，但多数平台不支持通配符嵌套，实际兼容性差
最稳妥的做法是：在 VSCode 终端里打标签前，先确认 CI 配置里 on.push.tags 的正则是否覆盖你的命名。别依赖图形界面随便输——VSCode 的标签输入框不校验格式。
