📘Git Tag 使用与推送技术文档
Git Tag 使用与推送技术文档
适用对象：日常使用 Git/GitHub 的研发工程师 使用场景：版本发布、里程碑标记、回滚定位、团队协作
1. 文档目的
在项目开发与发布过程中，Git Tag（标签） 是标记版本里程碑的核心工具，例如：
v1.0.0：正式发布版本v2.1.0-beta：测试版本v1.0.1：紧急修复版本
本技术文档用于统一团队对 Git Tag 的认知、创建方式、推送流程与规范，避免以下常见问题：
- 本地创建 Tag 后无法推送到 GitHub
- 正式版本误用轻量标签
- 标签删除不规范导致远程残留
- 团队成员标签不同步
2. Git Tag 类型说明（重点）
Git 支持两种标签类型，必须按场景正确选择。
2.1 轻量标签（Lightweight Tag）
定义：
- 仅是某个 commit 的别名
- 不包含作者、时间、备注等信息
特点：
- 创建速度快
- 结构简单
- 不可追溯变更背景
适用场景：
- 临时测试版本
- 内部调试标记
- 本地个人使用
示例：
git tag v1.0.0
2.2 附注标签（Annotated Tag，推荐）
定义：
- Git 官方推荐的标准标签类型
- 包含完整元数据（作者、时间、备注）
特点：
- 信息完整、可追溯
- GitHub Releases 页面可直接展示
- 支持生成发布说明
适用场景（强制）：
- 正式版本发布
- 对外发布版本
- 生产环境部署版本
示例：
git tag -a v1.0.0 -m "正式发布 v1.0.0，新增登录与支付功能"
✅ 规范建议：
- 正式版本 必须使用附注标签
- 轻量标签仅限本地或临时用途
3. 创建 Git Tag
3.1 给最新 Commit 创建标签
轻量标签
git tag v1.0.0
附注标签（推荐）
git tag -a v1.0.0 -m "发布 v1.0.0：完成核心功能"
3.2 给历史 Commit 补打标签
适用场景：
- 漏打历史版本标签
- 补充测试/回溯版本
操作步骤
- 查看提交记录
git log --oneline
- 给指定 commit 打标签
git tag -a v0.9.0 a3f2d4e -m "补打 v0.9.0 测试版本"
4. 推送 Tag 到 GitHub（核心）
⚠️ 重要说明： Git 默认 不会 推送 Tag，必须显式执行推送命令。
4.1 推送单个标签（推荐）
git push origin v1.0.0
适用场景：
- 正式发布
- 精准控制版本推送
4.2 推送所有本地标签（谨慎）
git push origin --tags
风险说明：
- 会推送所有未同步的标签
- 可能包含临时或错误标签
建议：
- 使用前确认本地标签干净
5. 查看与同步 Tag
5.1 查看本地标签
git tag # 仅标签名
git tag -n # 标签名 + 备注
5.2 查看远程标签
git ls-remote --tags origin
5.3 拉取远程标签（团队协作必备）
git fetch origin --tags
# 或
git pull origin --tags
6. 删除 Tag（高风险操作）
❗ 删除顺序错误会导致远程删除失败
6.1 删除本地标签
git tag -d v1.0.0
6.2 删除远程标签
git push origin --delete v1.0.0
兼容旧写法：
git push origin :refs/tags/v1.0.0
7. 常见问题排查
7.1 无权限推送 Tag
原因：未配置 GitHub 权限
解决方案：
- HTTPS：使用 Personal Access Token
- SSH：确认 SSH Key 已配置
ssh -T git@github.com
7.2 标签已存在（tag already exists）
原因：远程存在同名标签
解决方案：
- 标签正确：直接使用
- 标签错误：删除后重新创建
7.3 拉取后本地无标签
git fetch origin --tags
8. 版本号命名规范（强烈推荐）
8.1 语义化版本格式
v主版本号.次版本号.修订号
示例：
v1.0.0v1.2.3v2.0.0-beta
8.2 规则说明
| 字段 | 含义 |
|---|---|
| 主版本 | 不兼容变更 |
| 次版本 | 向后兼容的新功能 |
| 修订号 | Bug 修复 |
9. 高频命令速查表
# 创建标签
git tag v1.0.0
git tag -a v1.0.0 -m "备注"
# 推送标签
git push origin v1.0.0
git push origin --tags
# 查看标签
git tag
git tag -n
git ls-remote --tags origin
# 同步标签
git fetch origin --tags
# 删除标签
git tag -d v1.0.0
git push origin --delete v1.0.0
10. 总结（团队规范建议）
- ✅ 正式版本 统一使用附注标签
- ✅ 推送标签需显式执行
git push origin tag - ✅ 删除标签遵循：先本地 → 后远程
- ✅ 标签命名遵循语义化版本规范
该文档可作为：
- 团队 Git 规范附件
- 新人入职必读
- Release 流程参考文档
维护人：研发效能 / 平台团队