执行 git checkout v2.3.1 或 git checkout abc1234 后，终端出现一段红色提示：「You are in ‘detached HEAD’ state」。你没在意，继续写代码，git commit 也成功了。但当你执行 git checkout main 回到主分支后，刚才提交的改动完全不见了。git log 里找不到那个 commit，工作区也干净。这不是 Bug，是 Git 的预期行为——detached HEAD 上的 commit 不属于任何分支，切换后就变成悬挂对象，等待被垃圾回收。但在 90 天内，reflog 里还保存着它。
常见原因
1. git checkout <commit-sha> 或 git checkout <tag> 后直接提交
最常见场景。查看历史版本时切到了某个 commit，随手做了个修改并提交，完全没注意终端里的 detached HEAD 警告。
怎么判断：git reflog | grep 'HEAD detached'，若有输出，说明确实在 detached HEAD 状态下产生了提交。
2. CI/CD 流水线 git checkout 具体 SHA 进行构建
很多 CI 脚本会 git checkout $COMMIT_SHA 切到具体版本构建，若脚本中有修改文件并 commit 的步骤，就会在 detached HEAD 上产生提交，流水线结束后这些 commit 就消失了。
怎么判断：查看 CI 日志是否有 detached HEAD 提示，以及后续 commit 步骤是否成功但远端没有变化。
3. git bisect 过程中意外提交
git bisect 运行时会让 HEAD 处于 detached 状态。若在 bisect 过程中误执行了 git commit，这个 commit 会落在 detached HEAD 上。
怎么判断：git bisect log 查看 bisect 历史，确认是否在 bisect 期间有额外的 commit。
4. git worktree add 用了 commit SHA 而非分支名
git worktree add ../hotfix abc1234 会创建一个 detached HEAD 的 worktree，在其中提交的内容不属于任何分支。
怎么判断：git worktree list 查看是否有标注 (detached HEAD) 的 worktree，且该 worktree 下有新提交。
5. submodule 初始化后进入 submodule 目录提交
submodule 被检出时默认处于 detached HEAD 状态（指向特定 commit 而非分支）。若进入 submodule 目录后修改文件并提交，这个 commit 不在 submodule 的任何追踪分支上。
怎么判断：cd submodule-dir && git log --oneline -3，若 HEAD 后面显示的不是分支名而是 SHA，就是这种情况。
6. GitHub Actions 的 actions/checkout 默认行为
actions/checkout 在 Pull Request 事件下会 checkout 一个合并后的中间 commit，处于 detached HEAD 状态。若工作流步骤中有提交操作，commit 不会进入任何分支。
怎么判断：Actions 日志里搜索 HEAD is now at，看后面是否没有分支名。
最短修复路径
Step 1：如果还在 detached HEAD 状态，先不要切换分支
记录当前 HEAD 的 SHA：
git log --oneline -5
# 记住最新那个 commit 的 SHA，例如 deadbeefStep 2：创建新分支保存这些 commit
git branch save/detached-work deadbeef
# 或者直接从当前位置创建：
git checkout -b save/detached-workStep 3：如果已经切换了分支，用 reflog 找回 SHA
git reflog | grep -A3 'HEAD detached'找到 detached 期间最后一个 commit 的 SHA（通常在切走前的最后一个 commit 条目）。
Step 4：验证 SHA 内容
git show <sha>
git diff <sha>^ <sha>确认是你要找的改动后继续。
Step 5：把丢失的 commit 接回目标分支
# 切回目标分支
git checkout feature/my-work
# 备份
git tag backup/before-detached-recovery HEAD
# cherry-pick 找到的 commit（若有多个连续提交）
git cherry-pick <oldest-sha>^..<newest-sha>Step 6：清理临时分支（可选）
git branch -d save/detached-work预防建议
- 切到具体 commit 查看历史时，改用
git switch --detach <sha>并在终端配置颜色提示，让 detached 状态更醒目。 - 在 shell 提示符（PS1）里显示 Git 分支状态，推荐使用
starship或oh-my-zsh git插件，detached HEAD 会用特殊颜色标出。 - 如果需要在历史版本上做实验，始终先创建一个临时分支：
git checkout -b experiment/from-v2.3.1 v2.3.1。 - 在
CLAUDE.md/AGENTS.md中写明：AI agent 在执行 git checkout 时必须确认当前 HEAD 是否在分支上，避免在 detached 状态下提交。 - CI 脚本中若需要在特定 SHA 上构建，使用
--no-commit操作，避免意外产生悬挂提交。 - 配置 reflog 保留期：
git config --global gc.reflogExpire 180，给自己更多找回时间。 - submodule 工作流中进入 submodule 目录前，先
git checkout <branch>切到分支而非在 detached 状态操作。
常见问答 (FAQ)
Q: detached HEAD 上的 commit 什么时候会被真正删除？
A: git gc 时清理悬挂对象，默认 reflog 过期时间是 90 天（gc.reflogExpire）。到期后执行 git gc 或 git gc --prune=now 才会真正删除。所以只要在 90 天内操作，找回几乎是确定可以成功的。
Q: 我能直接在 detached HEAD 上 push 吗？
A: 不能直接 push，因为没有分支名。需要先 git checkout -b new-branch-name 创建分支，再 git push origin new-branch-name。
Q: git switch 和 git checkout 在处理 detached HEAD 上有区别吗？
A: git switch 默认拒绝在 detached HEAD 下操作，必须加 --detach 才能切到 commit，这样设计更安全。git checkout 没有这个保护，更容易误入 detached 状态。推荐迁移到 git switch 工作流。
Q: 能不能配置 Git，在 detached HEAD 下自动阻止 commit？
A: 可以通过 pre-commit hook 实现。在 .git/hooks/pre-commit 中加入检查：if git symbolic-ref -q HEAD > /dev/null 2>&1; then echo "Error: in detached HEAD state" && exit 1; fi。
相关阅读
- Rebase 之后 commit 消失了
- 找回 Git 历史里的旧版本文件
- Worktree 在分支删除后变成幽灵
- Submodule 怎么都拉不到最新 commit
- Force push 覆盖了队友的 commit
- AI 意外修改了 Git 历史
- AI 帮你回滚代码改动
标签: #git #version-control #排查