Git LFS pull报错unexpected EOF：tempfile写入故障排查

git lfs pull最让人上火的地方，是它往往在你以为万事俱备的时候给你一记闷棍：仓库 clone 下来了，代码看着都在，偏偏执行 pull 拉大文件时抛出一句cannot write data to tempfile "/root/8dc6d01e84acccd8a5769d5": LFS: unexpected EOF，然后进程退出，留下一堆没下完的指针文件。Git LFS 也就是 Large File Storage，干的事情很朴素——把大文件实体挪到仓库之外的存储上，仓库里只保留一个几百字节的指针文本，pull 或 checkout 的时候再把实体取回来替换掉指针。这条链路里，取数据、写临时文件、校验、改名入对象目录，每一步都可能断，而报错里那个显眼的tempfile和EOF，恰好把锅指向了"写"这一环，而不是很多人第一反应认为的"网不好"。我把这类报错在本地开发机、容器环境、CI 流水线里都碰到过，也在帮别人看问题时见过各种离谱的成因，从磁盘写满到挂载只读，从并发把带宽打崩到服务端对象根本不存在。这篇内容就是把我自己的排查顺序、命令、参数和踩过的坑完整摊开，适合被 LFS 卡住的开发同学、负责构建环境的运维同学，以及刚接手一个巨型仓库、还没搞清楚 LFS 脾气的朋友，不管你基础如何，照着走一遍基本都能定位到问题所在。

1. 把这行报错读透：它其实指向三个不同的故障点

1.1 报错三段式的结构拆解

这条错误信息看着长，实际可以切成三段来看：cannot write data to tempfile是动作描述，"/root/8dc6d01e84acccd8a5769d5"是出问题的对象，LFS: unexpected EOF是根因描述。第一段非常重要，它明确告诉你失败发生在"写入临时文件"这个动作上，而不是"下载失败"或者"校验失败"。第三段的unexpected EOF来自 Go 语言的io.ErrUnexpectedEOF，含义是"数据流在预期结束之前就断了"，读不到该有的字节数。问题在于，这个 EOF 的观测点是在写入侧，所以它既可能是上游供数端断了，也可能是下游落地端写不进去，两种完全不同的根因被压成了一句话，这就是为什么很多人换了网络、关了防火墙依然复现。

我习惯先分清这个报错属于"读不动"还是"写不下"。判据很简单：如果同一条命令换个目录、换台机器能跑通，多半是写的问题；如果换个目录依然在同一时刻断在同一个文件上，多半是读的问题。这个判据不绝对，但能帮你省掉大量无效尝试。另外注意LFS:这个前缀，它说明错误是由 LFS 自己的过滤器进程抛出的，不是 git 本体，所以你去翻 git 的报错文档基本找不到对应解释。

1.2 为什么 EOF 会出现在"写"这一步

要理解这一点，得先知道 LFS 拉一个大文件的完整流程：先向存储端发起请求，拿到一个字节流；然后在本地的临时目录里创建一个随机命名的临时文件；边接收边往这个临时文件里写；写完之后做一次完整性校验，通常是算长度或者算哈希；校验通过再把这个临时文件重命名，挪进对象目录，文件名就是那个 OID。整个过程是流式的，不是"全部下完再写"。

打个比方，你拿一根水管往水桶里灌水，桶底有个洞。你站在出水口看，会以为是上游水压不够，因为水面一直涨不上去。unexpected EOF就是这么个现象——写入端的缓冲区没写满就发现流结束了，于是抛出异常。真实情况可能是上游水断了，也可能是桶根本装不下、写盘返回了错误导致连接被提前关闭。我在一台磁盘配额只剩几百兆的机器上反复复现过这个报错，当时网络完全正常，抓包能看到数据确实在往下走，只是写到某个点就崩，因为临时文件把最后一点空间吃光了。

1.3 临时文件落在 /root 意味着什么

这条报错里最有信息量的其实是路径：/root/8dc6d01e84acccd8a5769d5。这个无扩展名、纯十六进制随机串的文件名，是典型的TempFile命名风格，通常出现在 LFS 计算出来的临时目录里。按默认行为，LFS 的临时文件应该落在仓库的.git/lfs/tmp或者对象目录下面，现在却跑到了/root根目录下，这本身就是个值得追的线索。

可能的情况有这么几种：仓库本身就放在/root下的某个目录，进程的工作目录或临时目录被解析成了它的上级；容器的HOME环境变量指向/root，某些临时文件创建逻辑参考了这个值；TMPDIR被设置成了/root；或者 LFS 的本地存储路径被改过，配置项落到了一个比较随意的地方。要验证这一点，最直接的是跑一遍git lfs env，它会把你当前环境里所有关键路径全部打出来。

注意：git lfs env的输出里，路径的取值优先级是配置文件高于环境变量、环境变量高于默认值，所以看到异常路径时，先翻.lfsconfig和git config --list，再查环境变量，顺序反了容易白折腾。

2. 四个层面的根因排查：从磁盘先看，别急着怀疑网络

2.1 磁盘空间与 inode：最常见的真凶

我处理过的这类报错里，超过一半是空间问题，而且相当一部分人只看df -h就下了结论"空间够啊"，然后一头扎进网络排查里出不来。真正要看的至少有两个指标：块空间和 inode 数量。块空间不够会直接写失败，inode 耗尽则会表现为"明明还有几十 G，就是创建不了新文件"，而临时文件恰恰需要创建新的 inode。

df -h /root /root/.git 2>/dev/null df -i /root /root/.git 2>/dev/null du -sh ~/.git/lfs 2>/dev/null

判断标准不是"剩余空间大于零"，而是"剩余空间要能扛住你要拉的最大单个文件"。因为流式写入的过程中，临时文件会在对象目录落地之前独占一份空间，如果你同时拉了多个文件，占用还要叠加。我的经验阈值是：剩余空间至少是最大单文件体积的两倍，并发数大于 1 时按并发数再乘一遍。一个 3G 的模型文件、并发 4，理论上峰值能吃掉十几 G，只剩 5G 的机器必然崩。

容器场景要额外注意。容器镜像的分层文件系统，可写层往往有独立的空间限制，df -h看到的是宿主机或者挂载卷的数字，可写层本身可能早就满了。这时候你在容器里看什么都正常，一写就报错。还有一类隐蔽情况是磁盘配额，普通用户视角下空间充裕，实际配额已经打满，quota -s或者查看挂载参数能确认。

2.2 权限与挂载属性：能读不能写

空间够却写不进去，接下来就该怀疑权限。这里有几个层次要分开看。目录本身的属主和权限位是一层，如果当前用户对目标目录没有写权限，创建临时文件会立刻失败。挂载属性是第二层，只读挂载、被重新挂成只读的文件系统，都会让写入失败，而且报错信息通常不会直白地告诉你"磁盘只读"。第三层是安全模块策略，某些加固过的环境会对特定目录的写入做额外限制。

ls -ld /root touch /root/.lfs_write_test && echo "可写" && rm -f /root/.lfs_write_test mount | grep -E " /root | / "

挂载被重挂成只读是很典型的一种故障，尤其是在虚拟机或者云主机上，底层存储出问题时文件系统会自动切到只读模式保护数据，表现就是原来能跑的任务突然全部写入失败，重启才恢复。如果你发现touch都失败但cat正常，基本可以锁定这个方向。另外要注意容器里以非 root 用户运行的情况，镜像里/root的属主是 root、权限通常是 700，换个用户跑就完全进不去，这个坑在 CI 里特别常见，因为 CI 的执行用户经常和本地不一样。

2.3 网络链路：断流、超时与不稳定的分片

排除掉本地之后，才轮到链路。LFS 拉大文件是个长连接、长时间的过程，中间任何一环都可能把它掐掉。企业网关、负载设备、安全设备对长连接和空闲连接通常有超时策略，LFS 默认的活动超时是 30 秒，意思是 30 秒内没有数据传输就认为连接死了。如果网络抖动导致几次重传、数据流暂停超过这个值，就会中断，表现出来正是 EOF。

另一个高频问题是并发。LFS 默认同时开 8 个传输任务，在小带宽环境下这 8 条流互相抢带宽，每条都跑得很慢，慢到触发超时，于是整体失败。这个现象很有迷惑性，因为单独拉一个小文件完全正常，一拉大文件就崩，看起来像是"大文件有问题"，实际是并发把链路压垮了。

git config lfs.concurrenttransfers 1 git config lfs.activitytimeout 120 git lfs pull

把并发降到 1、超时拉长到 120 秒，如果这样能跑通，基本可以确认是链路承载能力或者超时策略的问题，接下来的工作就是找一个稳定的并发值，而不是继续深挖报错文本。判断是否真断了还有个笨办法：在拉取的同时用ss -tnp或者系统自带的连接查看工具盯一下连接状态，看是不是有连接进入了异常状态。

2.4 服务端与仓库侧：对象真的存在吗

还有一种情况，本地环境无可挑剔，网络也很稳，就是拉不下来。这时候要怀疑对象本身。LFS 的指针文件里存的是一个 OID，pull 的时候按这个 OID 去存储端取，如果这个对象压根不存在、或者权限不允许你访问、或者仓库的 LFS 端点配置指向了一个错误的地方，都会失败。历史被重写、分支被强制推送、仓库从别处迁移过来但大文件没跟着迁移，都会留下这种"指针在、实体没了"的状态。

git lfs ls-files -l git lfs fsck git config --get-regexp "lfs|remote" cat .lfsconfig 2>/dev/null

git lfs fsck会检查本地指针和对象的对应关系，能报出哪些对象在本地缺失或者损坏。.lfsconfig这个文件容易被忽略，它提交在仓库里，会覆盖本地的 LFS 端点配置，如果它被改成了一个访问不到的地址，你在本地怎么调git config都是白费劲。我的习惯是先看这个文件，再看git config --get-regexp的输出，最后才去动全局配置。

3. 一套可复现的排障流程：我平时按这个顺序走

3.1 第一步：留证据，别急着改配置

很多人一出错就条件反射地改配置、删缓存、重装 LFS，改完之后问题要么消失了要么变得没法复现，两种情况都糟糕。我的做法是先固定现场：把git lfs env的完整输出存下来，把当次的 LFS 日志导出来，再跑一次带调试开关的命令，把网络交互的过程也记录下来。

git lfs env > /tmp/lfs-env.txt 2>&1 git lfs logs last GIT_TRACE=1 GIT_CURL_VERBOSE=1 git lfs pull 2>&1 | tee /tmp/lfs-pull.log

git lfs logs last会直接打开最近一次的 LFS 日志，里面通常有比你看到的终端报错更详细的信息，包括请求了哪个对象、返回了什么状态、在哪个字节位置断的。加上GIT_CURL_VERBOSE之后，你能看到 HTTP 层面的状态码和传输细节，如果是服务端返回了异常状态码，这一步就能直接抓到。这些证据在找托管平台支持人员排查时也是必需的，没有日志的工单基本只能得到"请重试"的回答。

3.2 第二步：单文件定点复现，把范围缩到最小

全量 pull 失败的时候，你不知道是某一个文件的问题还是所有文件的问题，所以第二步要做的就是把范围缩到一个文件。先用git lfs ls-files -l列出所有指针和对应的 OID，挑一个体积大的、或者报错日志里出现过的，定点拉取。

git lfs fetch origin <oid> # 或者按路径限定 git lfs pull --include="models/xxx.bin"

定点拉取的好处是结果干净：成功了说明问题出在并发或整体负载上，失败了说明问题出在这个对象或者这条链路上，两种结论对应的排查方向完全不同。我一般会再挑一个体积很小的对象做对照，如果小文件能拉、大文件不行，那空间和超时的嫌疑立刻上升；如果连小文件都失败，那就得往权限和端点配置上查。

3.3 第三步：参数降级，先跑通一次再谈优化

定位到方向之后，我倾向于先用最保守的参数跑通一次，拿到一个"能用"的基线，再去逐步加压找上限。这一步的核心是把并发降到 1、超时拉长、必要时强制走最简单的传输方式。

git config lfs.concurrenttransfers 1 git config lfs.activitytimeout 300 git config lfs.transfer.maxretries 10 git config lfs.basictransfersonly true git lfs pull

跑通之后记得把配置记下来，别稀里糊涂地一直挂着。lfs.basictransfersonly强制使用最基础的单次传输方式，牺牲速度换稳定性，在链路质量差的环境里非常有效。等稳定跑通几次之后，再把并发慢慢往上调，2、4、8 各试一轮，找到一个既不超时又不至于慢到无法接受的平衡点。这个过程听起来笨，但比反复猜测靠谱得多。

3.4 第四步：清理残留与重建缓存

LFS 的临时文件在传输中断之后不会自动清理，这一点很多人不知道。失败几次之后，.git/lfs/tmp下面可能堆着一堆半截文件，白占空间，还会让后续的拉取更容易因为空间不足而失败，形成恶性循环。清理的时候要注意分寸，只清临时目录和缓存，不要一上来就把整个.git/lfs删掉，那里存着已经下载好的对象，删了就得全部重下。

du -sh .git/lfs/tmp .git/lfs/objects .git/lfs/incomplete 2>/dev/null rm -rf .git/lfs/tmp/* rm -rf .git/lfs/incomplete/* git lfs prune --dry-run git lfs prune

先--dry-run看一眼会删掉什么再执行，是我养成的习惯。git lfs prune会清理那些当前分支不再引用、且超过保留期的对象，正常使用是安全的，但在你还原某些历史提交的时候要留神，删了就得重新下载。清理完之后再跑一次 pull，如果这次成功了，说明之前就是残留文件和空间叠加导致的失败。

3.5 第五步：迁移存储目录，从根上解决空间问题

如果确认是空间不足，而机器上还有别的盘，最省事的方案是把 LFS 的本地存储整个挪过去，而不是天天清理。LFS 支持通过lfs.storage指定存储根目录，配置之后新下载的对象会落到新位置。

mkdir -p /data/lfs-storage git config lfs.storage /data/lfs-storage git lfs env | grep -i storage

配置完之后用git lfs env确认路径确实变了，再跑一次 pull 验证。这个配置可以写在仓库级，也可以写在全局，看你的使用习惯。仓库级的好处是不影响别的项目，全局的好处是每接一个新仓库都自动生效。我个人偏向全局配置，配合一个专门的数据盘，能避免绝大多数因为磁盘写满导致的 LFS 故障。

4. 参数与配置详解：把 LFS 调到"能跑完"的状态

4.1 六个真正有用的配置项

LFS 的配置项不少，但真正影响这类报错的就那么几个，我把它们整理成一张表，方便对照着调。默认值是参考值，不同版本可能有细微差异，以你本地git lfs env的输出为准。

调参的原则是"一次只改一个"。同时改三个参数然后成功了，你并不知道是哪个起了作用，下次遇到同样问题还是得重来一遍。我自己的顺序是先降并发，不行再拉超时，再不行提高重试次数，最后才考虑强制基础传输。

4.2 临时目录与对象目录分开管理

很多人把临时文件和对象文件混为一谈，其实它们在磁盘上是两个位置，占用规律也不同。对象目录存的是下载完成、校验通过的文件，会长期保留；临时目录存的是下载中的半成品，正常情况下用完就删。分开管理的好处是你可以把临时目录指向一个空间充裕的临时盘，把对象目录留在稳定的数据盘。

export TMPDIR=/data/tmp mkdir -p "$TMPDIR" git lfs env | grep -i temp

TMPDIR这个环境变量会影响很多工具的行为，不只是 LFS，改之前要想清楚会不会影响别的程序。在容器编排里，更常见的做法是直接给工作目录挂一个大一点的卷，而不是去折腾临时目录。还有一个细节：临时目录和对象目录如果不在同一个文件系统上，最后的"重命名入位"操作会退化成复制，反而更慢更耗空间，所以能放同一个分区就放同一个分区。

4.3 大仓库的按需拉取策略

如果一个仓库大到全量 pull 根本不现实，那就别硬来。LFS 支持按路径过滤，只拉你真正需要的那部分文件，剩下的等用到了再说。

git lfs pull --include="assets/ui/**" git lfs pull --exclude="*.psd" git config lfs.fetchinclude "src/**"

另一个思路是在 clone 阶段就跳过 LFS 的自动下载，先把代码拿到手，再按需拉文件。设置GIT_LFS_SKIP_SMUDGE=1之后，checkout 出来的只是指针文件，仓库体积很小，速度很快，需要哪个文件再单独 fetch。这个方案特别适合只需要看代码、不跑构建的场景，比如代码审查或者临时查一个实现细节。需要注意的是，跳过之后忘记拉，构建会因为找不到实体文件而失败，报错信息通常长得不像 LFS 相关，容易绕远路。

5. 常见问题速查表与踩过的坑

5.1 现象与处理动作对照

5.2 几个文档里不会写的坑

第一个坑是"只查空间不查 inode"。我见过一台机器df -h显示还有 40G，df -i显示 inode 已经 100%，任何新文件都创建不了，报错正是这个 EOF。第二个坑是"CI 跑通就当本地没问题"。CI 环境往往是干净容器、独立缓存、固定网络，和本地差异巨大，反过来也成立，本地正常不代表 CI 正常，两边都要看。第三个坑是"并发越大越快"。这条在 LFS 上基本是反的，并发过高只会让每条流都慢到触发超时，整体成功率反而下降。

第四个坑是"看到 EOF 就删整个.git/lfs"。这个目录里可能有你花几个小时才下完的对象，删掉重来成本很高，正确做法是先清tmp和incomplete。第五个坑是"忽略校验失败和 EOF 的区别"。EOF 是数据没传完，校验失败是传完了但对不上，前者查链路和空间，后者查对象本身和存储端是否被篡改，方向不一样，混着查只会浪费时间。

提示：中断多次之后，务必看一眼.git/lfs/tmp的占用，这个目录不会自动瘦身，长期不管能吃掉几个 G。

6. 让这类问题少发生：仓库侧与机器侧的习惯

6.1 仓库侧该守的规矩

从源头控制体积是最有效的办法。我在参与维护的仓库里推过几条硬规矩：单文件超过一定阈值就必须走 LFS，二进制产物不提交到普通分支，历史里的大文件定期用迁移工具清理。这几条听着简单，执行起来能挡掉绝大多数"仓库越用越臃肿"的问题。另外.lfsconfig这个文件要纳入评审，它一旦被改成错误地址，所有协作者都会中招，而且报错信息完全不会提示是这个文件的问题。

还有一点容易被忽略：分支策略和 LFS 的关系。频繁地强制推送、重写历史，会让 LFS 对象产生大量孤儿，既占存储空间，又可能让某些旧提交拉不下来。如果团队确实需要重写历史，事后要有人负责核对 LFS 对象是否完整，别等别人 clone 失败才发现。

6.2 机器侧该做的监控

对经常跑构建的机器，我会加两条最简单的监控：磁盘剩余空间和 inode 使用率，阈值设在 20% 告警。这两条不需要什么复杂工具，一个定时脚本加一封邮件就够，但能挡掉大部分"半夜构建失败"的事故。容器环境再补一条：可写层的空间使用率单独看，别被宿主机的数字骗了。

另一个实用习惯是给 LFS 单独划一块存储。我在几台常做构建的机器上都配了lfs.storage指向数据盘，配合定期git lfs prune，基本没再因为空间问题失败过。清理策略要保守一点，保留期设长一些，宁可多占点空间，也别把还在用的对象删了。

最后分享一个我自己反复验证过的小技巧：遇到这种报错，先别急着改任何东西，跑一遍df -h、df -i、git lfs env这三条命令，把输出存下来，再决定往哪个方向走。这三条命令加起来不到十秒，但它们能排掉我遇到过的六成以上同类问题。剩下那四成里，一半靠降并发和拉超时解决，另一半基本都得靠日志去找服务端的原因了。真正需要动到重装或者重拉整个仓库的情况，我这些年也就碰上过两三次。