结论是必须使用 post-receive 服务端钩子，在接收 push 后解析 refs/heads/release/v2.1 等分支名，提取版本号、校验格式、用绝对路径 git 命令创建带注释标签并显式指定 commit，同时检查标签是否已存在以避免重复，全程需确保权限、路径和环境变量正确。
如何用 Git 钩子在 push 时自动根据分支名打标签
直接结论：不能靠 pre-push 钩子打标签再推送——它运行在本地，但标签还没推送到远程，别人拉不到；真正可行的是用 post-receive 钩子，在服务端接收 push 后解析分支名、创建并推送标签。
常见错误是写个本地脚本，git tag 之后没 git push --tags，或者误以为 pre-push 能修改即将推送的内容（Git 不允许）。
-
post-receive是唯一能可靠触发的时机：它收到完整 ref 更新（比如refs/heads/release/v2.1），此时可安全读取分支名 - 分支名需提前约定格式，例如
release/vX.Y、hotfix/1.0.5，否则无法稳定提取语义版本 - 标签名建议与分支名映射但不照搬，避免斜杠冲突（
git tag不支持/），可用下划线替换：release_v2.1 - 必须用
git --git-dir /path/to/repo.git tag -a -m "auto tag from release/v2.1" release_v2.1 refs/heads/release/v2.1显式指定 commit，不能只写分支名（钩子里当前工作区不可靠）
分支名解析逻辑怎么写才不容易出错
别用 cut -d'/' -f2- 这类简单切分——如果分支叫 feature/user-login-flow，你可能只想对 release/ 和 hotfix/ 打标签，其他忽略。
核心是匹配前缀 + 提取有效段，不是单纯截字符串：
- 先用
case "$refname" in refs/heads/release/*)做前缀判断，比正则更轻量、更安全 - 提取版本号推荐用
basename "$refname"拿到v2.1，再用sed 's/^v//'去掉开头v（如果约定带 v） - 避免用
git rev-parse --abbrev-ref HEAD——钩子里没有 HEAD，也不在工作区，这个命令会失败 - 校验版本格式：用
[[ $version =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || [[ $version =~ ^[0-9]+\.[0-9]+$ ]]防止release/bad-branch误打标签
服务端钩子权限和路径容易踩哪些坑
最常见的问题是：钩子脚本能执行，但 git tag 报错 fatal: Not a git repository 或提示权限拒绝。
- 务必用绝对路径调用
git，例如/usr/bin/git，别依赖 PATH（钩子环境 PATH 往往极简） -
--git-dir必须指向 bare repo 根目录（如/var/git/myapp.git），不是.git子目录 - 钩子文件权限要是
755，且属主和仓库属主一致（否则git拒绝写入 refs/tags/） - 标签创建后要显式
git push origin --tags？不用——post-receive里直接操作 bare repo 的 refs 就是最终态，不需要再 push
要不要加防重逻辑：同一分支重复 push 怎么办
要加。用户 git push --force 到已处理过的 release/v2.1，你不拦截就会重复打同名标签，Git 允许覆盖但语义混乱。
- 检查标签是否已存在：
git --git-dir "$GIT_DIR" show-ref --verify --quiet refs/tags/$tagname - 如果存在，用
git --git-dir "$GIT_DIR" rev-parse refs/tags/$tagname对比 commit ID，仅当 commit 不同时才更新（用-f强制覆盖） - 记录日志到文件（如
/var/log/git-auto-tag.log），方便排查“为什么没打标签”——多数时候是分支名不匹配或版本校验失败 - 不要静默跳过：对不匹配的分支也记一条 info 日志，否则运维查问题时完全没线索
真正的难点不在脚本语法，而在于服务端环境隔离性差、权限链路长、错误无回显。每次改完钩子，一定用 echo test >> /tmp/hook-debug 加一句调试输出，再手动模拟 push 测试。
