Git报错unpack failed? Missing tree对象缺失的排查与修复

如果你的 Git 服务器日志里出现过 unpack failed，并且紧跟一句 error Missing tree，那次推送大概率是被服务器拒绝了。这组错误看起来像传输问题，但我实际排查下来的结论往往完全不同：它不是在说网络断了，而是在说服务器端的对象库本身存在一个“洞”。最典型的现场是：你本地仓库完整无损，git log、git status 全部正常，但一执行 git push，远端就抛出一串 remote: error: unpack failed: error Missing tree ...，甚至会把整次推送挡在门外。

这一类报错在自建 Git 服务、代码库迁移、镜像同步、以及多人协作仓库里经常出现。尤其是那些跑了一年以上的老仓库，历史分支多、tag 多、中间有人做过 GC 或手工清理，最容易在某个时间点突然踩中。它不会提前给你警告，也不会立刻把仓库弄崩，只会在某一次 push 或 fetch 时冷不丁冒出来。这篇文章我想把这类错误的完整排查思路、常见的产生根源、以及从客户端到服务端的修复手段一次讲清楚。

1. Missing tree 报错背后，Git 到底在做什么

1.1 从“unpack”到“ref update”的运作链路

看报错不能只看表面。error: unpack failed 中的 unpack，是指 Git 服务端在收到推送数据后，需要把传过来的“pack 包”解开或索引化。这个过程通常由 git receive-pack 在处理 git push 时触发。

正常推送的链路大概是这样的：

1. 本地仓库运行 git push，把本地提交、tree、blob 对象打包成一个 pack 文件，传给远端。
2. 远端收到数据后，先执行 unpack 或者 index-pack，把对象从传输格式变成可寻址的 Git 对象。
3. 远端把新接收到的对象写入对象库，再尝试更新目标分支引用。
4. 如果这一步没有通过完整性校验，远端就会返回 unpacker error 或类似报错。

Missing tree 并不是说 pack 文件本身坏了，而是说在解开 pack、准备把这些对象关联到已有历史时，Git 发现某个 commit 所指向的 tree 对象在对象库里不存在。你可以把 Git 仓库想成一个仓库货架：commit 是货物清单，tree 是货架分层结构，blob 是具体货物。如果只收到一张清单，但发现清单指向的那一层货架压根不存在，Git 自然没办法继续干活。

unpack failed 的报错常见于 push 场景，但 fetch 场景下也可能在客户端本地看到类似抛出。二者的共同逻辑都是：无论哪一端，在把接收到的对象连接到已有对象图时，发现了一个“空洞”。

1.2 “Missing tree”到底缺的是什么东西

很多第一次遇到这个报错的人会下意识以为是代码文件缺失，其实不是。Git 里的对象一共有四种类型：

• blob：文件内容快照
• tree：目录结构快照，记录“这个目录下有哪几个子项”
• commit：一次提交的元信息，包含作者、提交信息，以及最顶层的 tree ID
• tag：附注标签对象

checkout 一个提交时，Git 会先从 commit 对象找到它记录的 root tree，然后递归展开整棵 tree 结构，才能还原出完整工作区。如果那一层 tree 缺失，你手里就只有一次提交的“封面”，没有实际目录骨架。

tree 对象本身在仓库里通常很小，但它承担着一个 commit 可以正常还原文件的全部依赖。缺失 tree 的一大特点是：commit 对象可能还孤零零地存在，所以用 git log 还能看到提交记录，但一旦尝试 checkout、diff、merge，或服务器在接收新对象时执行连通性检查，就会立刻暴露。

这里需要区分一下：Missing tree 不等于 Unable to read tree。前者是 Git 明确告诉你某个对象 ID 不存在，后者可能是权限问题或文件损坏。排查方向完全不同。

2. 我见过的几类真实现场，根源大多不是最近这次操作

2.1 更容易踩坑的仓库布局

结合我排查过的案例，容易出 Missing tree 的仓库通常有几类共同点：