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 的仓库通常有几类共同点：

这些场景有一个共同点：它们都不是“你刚刚提交的代码有问题”，而是仓库的历史对象库里早就出现了窟窿。只是窟窿还没有被触及时，普通操作看不出异常。

我曾经处理过一个很典型的案子。一个自建 Git 服务上有个项目，日常开发正常，某天有同事往上推一个新分支，服务器立刻返回 error: unpack failed: error Missing tree。一开始所有人以为是新分支里有什么特殊文件导致服务端不兼容，后来查了一圈才发现，问题出在一个已经删掉的老分支上。那个老分支被删除后，上面的历史提交和树对象变成了不可达对象，随后某次 GC 触发时被清掉了。新分支推送时，Git 在做连通性检查时顺着历史节点往回走，正好撞到那棵缺失的树。

2.2 为什么服务端仓库会自己逐渐“漏”对象

Git 本身的 GC 机制是设计得比较安全的，但如果操作顺序不对，就会出现漏洞。比较常见的组合是：先删除分支或 tag，紧接着在很短时间内执行 git gc --prune=now，把本应保留两周的不可达对象直接清掉。

举个例子，默认配置下，git gc 只会清理“超过两周且不可达”的对象。这个设计是有道理的，因为两周期限内可能会有人想恢复误删分支。但如果有人为了清理磁盘主动用了 --prune=now，那就等于跳过了安全期限，把所有不可达对象立即销毁。

更隐蔽的是 alternates 机制。有些仓库为了节省磁盘，会在 .git/objects/info/alternates 里写另一个仓库的对象库路径，让 Git 去借用对象。这样确实省空间，但同时也制造了一个隐式依赖。一旦被依赖的仓库做了 GC 或迁移，你的仓库就可能瞬间缺对象。而且这种缺失经常不是一次性全部缺，而是缺其中一个 tree，表现得非常零碎。

另外，自建 Git 服务端如果对仓库做了 mirror 或 partial clone，也容易埋雷。比如 git clone --mirror 虽然会拉全量分支，但如果源仓库本身存在缺口，镜像上的对象也天然缺。又比如用 --filter=tree:0 做部分克隆，后续 GC 策略没配好，远端按需对象过期后，本地就会出现缺失。

3. 定位“谁缺了哪个对象”的完整排查链路

3.1 先收集现场，判断是接收端缺还是来源端缺

遇到报错不要太快动手，更不要直接删掉仓库重新 clone。第一步是先确认报错到底出现在哪一端。同样是 Missing tree，可能是接收端（push 时是服务器，fetch 时是本地）缺，也可能是发送端根本没有这个对象。

最直接的确认方式是把日志完整保存下来。比如 push 时报错，通常能看到类似信息：

text复制remote: error: unpack failed: error Missing tree a3f2b8c1e5...
To git@example.com:myproject.git
 ! [remote rejected]  main -> main (unpacker error)

此时应该先登到服务端，在对应的裸仓库目录里执行：

bash复制git fsck --full --no-dangling

--full 会检查对象库中所有对象，而不仅仅是当前引用可达的部分；--no-dangling 可以避免输出大量“不是问题”的无主对象，让真正的 missing 信息更容易看到。

如果 fsck 输出里有 Missing tree <sha>，那基本可以确定服务端对象库缺对象。如果服务端 fsck 干干净净，反而要回头检查是不是客户端在打包时没有正确包含依赖对象。不过后者比较少见，绝大多数情况是服务端先缺。

3.2 用 fsck 和 rev-list 把缺失范围打出来

fsck 只能告诉你“有没有缺”，如果想知道影响面有多大，建议再用 rev-list 扫描一遍缺失对象。在故障仓库里执行：

bash复制git rev-list --objects --all --missing=print

输出中带有 ? 前缀的行就是缺失对象。例如：

text复制?tree a3f2b8c1e5a4c3d2e1f0...

这会帮你确认：到底只缺一棵树，还是缺了一批树。如果缺了一大批，说明问题可能出在某个目录层级的对象整体丢失；如果只缺一棵树，往往是某个特定历史路径被 GC 误伤。

当 fsck 给出缺失 tree 的 SHA 后，可以继续查询到底哪些提交引用了它。一个比较笨但有效的办法是遍历所有 commit，提取它的 root tree，看是否等于缺失对象：

bash复制git rev-list --all | while read c; do
  t=$(git rev-parse "$c^{tree}") 2>/dev/null || echo "commit $c cannot resolve tree"
  if [ "$t" = "a3f2b8c1e5a4c3d2e1f0..." ]; then
    echo "commit $c references missing tree"
  fi
done

如果缺失的不是 root tree，而是某个更下层的子 tree，那么 git cat-file -p 可以查看引用关系。先用：

bash复制git cat-file -p <commit-sha>

拿到 root tree，再用：

bash复制git ls-tree <root-tree-sha>

一层层往下找，直到定位到缺失子树的父级路径。

3.3 想更精确，可以看 pack 和 trace

如果 fsck 没有直接给出有效结论，或者你想确认是不是 pack 文件本身出了问题，可以去看对象库里有哪些 pack：

bash复制ls -lh .git/objects/pack/

重点检查 pack 文件和 idx 文件是否一一对应。如果只有 .pack 没有 .idx，或者文件大小明显异常，可以用 git verify-pack 验证：

bash复制git verify-pack -v .git/objects/pack/*.idx

这个命令会逐对象校验 pack 内容。要是输出的末尾带有 error 或 invalid 字样，说明 pack 可能已经损坏或者处于不完整状态。

在客户端做 fetch 操作时，还可以通过开启 trace 查看实际交互：

bash复制GIT_TRACE_PACKET=1 git fetch origin main

trace 日志会显示客户端和服务端之间的协议交互，能看到服务端承认发送了哪些 pack 数据。这适合用来判断到底是服务端漏发了对象，还是客户端解包后本地不认。但在多数 unpack failed 问题里，这一步不是必需的，通常 fsck 已经足够。

4. 不同场景的修复方案，以及为什么顺序很重要

4.1 浅克隆和部分克隆导致的历史不完整

如果你是在客户端本地做 fetch 或 clone 时报 Missing tree，需要先检查自己是不是一个浅克隆仓库。执行：

bash复制git rev-parse --is-shallow-repository

输出 true，说明本地有 .git/shallow 文件，历史边界被截断过。这种状态下如果服务端保留完整历史，通常用一条命令就能修复：

bash复制git fetch --unshallow

但有时候服务端同样已经被裁减过了，或者浅克隆时间太久，直接 --unshallow 会继续报缺失。这时可以退而求其次，用逐步加深的方式试试：

bash复制git fetch --shallow-since=2020-01-01 origin main

这个命令会告诉 Git 拉取 2020 年 1 月 1 日之后的历史对象。如果服务端确实保留到那个时间点，就能把缺口补上。它的原理是让服务端基于时间阈值重新裁剪发送范围，而不是一次性要求全量历史。如果连这个也失败，说明服务端源仓库的历史已经不完整，需要走后面的对象灌入方案。

对于使用过 --filter 的仓库，比如 git clone --filter=blob:none，缺失对象通常发生在 checkout 时按需回源失败。修复方式是重新完整拉取一次对象元数据：

bash复制git fetch --refetch origin

这个命令会强制重新走一次完整对象获取，不依赖本地已有缓存。实测下来很多 partial clone 造成的“假 missing”都能靠它解决。

4.2 用全量 bundle 把对象灌入故障仓库

当服务端仓库本身缺树，而本地开发机或其他源仓库还有一个完整副本时，最高效的方法是打包成一个 bundle 灌进去。bundle 可以理解成 Git 仓库的离线打包格式，适合在不通网络协议的情况下传递对象。

在完整仓库上执行：

bash复制git bundle create /tmp/full-repo.bundle --all

然后在故障服务端的裸仓库目录里执行：

bash复制git fetch /tmp/full-repo.bundle '+refs/heads/*:refs/backup/restore-*'

这一步的核心思路是：先把完整对象库导进来，但不直接覆盖任何现有分支引用。引用都被放在 refs/backup/ 命名空间下，相当于给仓库做了一个对象层面的“输血”。导完之后，再跑一次：

bash复制git fsck --full --no-dangling

如果 fsck 干净了，说明对象缺口已经补齐。这时可以删除临时恢复引用：

bash复制git for-each-ref --format='%(refname)' refs/backup/restore- | xargs -n 1 git update-ref -d

提示：删除临时引用前，务必确认 fsck 已经没有任何 Missing 错误。否则删完引用后，原本靠引用维持可达性的对象可能再次变成不可达对象，下一次 GC 又会被清掉。

这种 bundle 方案是我个人最推荐的一种，因为它的操作对象是“对象库”而不是“引用”，不会把故障仓库的分支指针搞乱，也不会产生强制推送那样的历史覆盖风险。

4.3 从上游或另一处源定向拉取特定提交来补对象

如果没有完整 bundle，但你知道某个源端包含缺失对象，可以试试直接在故障仓库里添加一个临时 remote，然后 fetch 指定提交。

假设你的源端仓库位于 /home/git/backup-repo.git，在故障裸仓库里执行：

bash复制git remote add repair /home/git/backup-repo.git
git fetch repair 'refs/heads/*:refs/backup/repair-*'

如果源端是 HTTP 或 SSH 远程地址，做法一样。重点在于：fetch 之后，对象才会被写入本地对象库，之后可以跑 fsck 验证。

不过，如果源端没有开启任意 SHA 拉取权限，你可能不能直接 fetch 一个裸 SHA。Git 服务端的默认策略是只允许 fetch 已经对外广播的引用。对于自建仓库，如果确认仓库环境可信，可以通过配置允许按 SHA 拉取：

bash复制git config uploadpack.allowReachableSHA1InWant true
git config uploadpack.allowAnySHA1InWant true

注意，allowAnySHA1InWant 会让别人在知道对象 SHA 的情况下，绕过引用直接拉取任意对象，有一定信息暴露风险。在公司内网、权限可控的仓库上可以临时开启，用完最好关掉。对外服务的仓库不要贸然打开。

4.4 修仓过程的禁区

我在实践中总结了几条修仓过程中特别容易加剧问题的操作，先说清楚，免得你踩同样的坑。

第一，不要在确认对象缺失前执行 git gc --prune=now。很多人一看到仓库报错，第一反应是“文件太多乱了吧，清理一下”，结果这一清，原本可能还残留的不可达对象被彻底删除，仓库从“缺一棵树”变成“缺一片历史”，彻底无法恢复。

第二，不要在没有备份的情况下直接对服务端仓库执行 git repack -a -d。repack 会把现有 loose 对象重新打包并删除旧 pack，如果过程中有对象丢失，原本零散但尚可抢救的对象可能被彻底覆盖。

第三，不要尝试用 git replace --graft 强行绕过缺失 tree。replace 机制可以让你把错误的提交替换成另一个提交，看起来 refs 正常了，但缺失对象仍然在对象库里。后续每个 clone 或 fetch 的人如果同步了 replace 对象，会把问题扩散到整个团队。这属于“掩盖问题”而不是“修复问题”。

第四，不要在缺失 tree 的状态下直接 git push --force。force push 只会改变远端分支指针，不会自动把缺失的 tree 对象补上。如果新提交历史仍然依赖旧 tree，force push 依然会失败；如果为了绕过失败强行制造一个不依赖旧历史的新提交，又会丢掉原有历史。很多补救代价都是从这里开始变大的。

正确的修复顺序永远是：先补齐对象，再修复引用，最后才做 GC 和 repack。

5. 让仓库不再隔三差五缺对象的基础配置

5.1 服务端打开对象完整性校验

很多自建 Git 服务默认没有开启接收时的对象校验。也就是说，服务端收到一个 pack 后，不一定立刻检查其中的 commit 和 tree 对象是否在自身对象库里都能闭合。等到下次真的需要读取时才发现问题，那时候已经晚了。

推荐在服务端统一开启两个开关：

bash复制git config --system receive.fsckObjects true
git config --system transfer.fsckObjects true

receive.fsckObjects 会在接收 push 时检查传入对象，提前拦截坏对象；transfer.fsckObjects 会在 fetch 和 push 两侧都做校验。这对大型仓库来说会有一点性能开销，push 速度会稍微变慢，但相对于半夜爬起来恢复仓库的成本，这点开销非常值得。

对于 Gitea、GitLab 这类集成系统，如果你的仓库托管在它自带的管理目录里，可能需要同时检查它们自身配置是否调用了 Git 的 fsckObjects 参数。很多图形化管理界面没有暴露这个设置，得通过部署机器上的 git config 全局配置来生效。

5.2 把 GC 策略调得足够保守

Git 默认的 GC 策略是：当对象数量或 pack 数量超过阈值时，自动执行 gc；默认清理超过两周的不可达对象。这个策略对大多数仓库是合理的。真正危险的是那些“手工优化”命令。

针对重要仓库，我给的建议比较保守但不难执行。

第一，不要日常用 git gc --prune=now，留给确实需要立即清理敏感信息的人去用，而且用之前必须先做全量 bundle 备份。

第二，可以适当延长不可达对象的保留时间。在服务端执行：

bash复制git config gc.pruneExpire "2.weeks.ago"

如果你希望更稳，可以设置成一个月，甚至更久。代价是磁盘上会残留一些不可达对象，但对核心仓库来说，多占一点磁盘换取可恢复性，我觉得非常值。

第三，避免在同一个仓库上同时开 partial clone 和频繁 GC。部分克隆的核心假设是“客户端可以从服务端按需回源”。如果服务端又在后台高频率 GC，把按需对象清掉，客户端就会在某个不确定时刻突然缺对象。凡是跑过 --filter 的仓库，要么关闭自动 GC，要么保证服务端保留足够长时间的对象供回源。

5.3 备份和巡检不能互相替代

我经常看到有人把“仓库目录复制一份”当成备份，或者把“每天 fsck 一次”当成备份。其实这是两件事。

fsck 只能发现已经存在的问题，它不能让对象从无到有。备份则是在问题发生前留下的“底牌”。一个健全的体系应该同时具备：