Go tar 为什么读取时报 unexpected EOF

Go 读取 tar 时出现 unexpected EOF，通常表示当前结构还需要字节，但底层输入已经结束：可能是文件正文少于头部声明的长度，也可能是头部、对齐填充或外层压缩流被截断。不能把它与正常的 io.EOF 一起忽略。

最短的排查路径是保留错误发生阶段和条目名，再核对生产端是否写够声明长度、是否完成关闭，以及传输层是否交付了完整字节。本文例子只读普通 tar，不向磁盘展开归档。标准库文档入口：https://pkg.go.dev/archive/tar。

先确认错误发生在头部还是文件正文

Next 负责取得下一条目的头部；对当前 tar.Reader 读取则取得该条目的正文。Header.Size 是逻辑正文大小，不是整个 tar 文件大小。头部、正文、填充属于不同结构，不能用文件总长直接替代正文长度判断。

正常条目读完时，当前正文读取可以遇到 EOF；归档正常结束时，Next 返回 EOF。相反，尚未满足正文长度就结束，错误意味着数据不完整。Go 的 tar.Reader 实现明确区分剩余长度与底层 EOF。本文不将某一次 Next 成功等同于归档整体完好。

用只读遍历保留条目名和读取阶段

先把原文件保留为只读输入，将下面代码保存为 main.go，由读者在自己的样例上运行。不要先修补归档尾部，也不要先把错误吞掉。例子不做格式自动识别，输入必须是普通 tar；.tar.gz 应按后文区分压缩层。

package main

import (
    "archive/tar"
    "errors"
    "fmt"
    "io"
    "os"
)

// InspectTar 仅诊断普通 tar，不解压、不创建归档中的路径。
func InspectTar(r io.Reader) error {
    tr := tar.NewReader(r)
    var total int64
    previous := ""
    for count := 0; ; count++ {
        h, err := tr.Next()
        if err == io.EOF {
            return nil // 仅在 Next 的归档结束位置接受 EOF。
        }
        if err != nil {
            return fmt.Errorf("读取条目头或跳过上一条 %q: %w", previous, err)
        }
        // 这是示例业务配额，不代表整个解析器的 CPU 或内存硬上限。
        if count >= 1000 || h.Size  (64

这里的关键不是打印所有文件，而是在 io.Copy 出错时保留条目名、声明大小和已读字节数。代码使用 %w 保留错误链，便于 errors.Is 判断；不按错误文字做业务分支。若出错发生在 Next，消息保留上一条名称，只说明故障可能位于剩余填充或下一个头部，不能武断认定就是上一文件正文。

预期行为是完整样例走到“tar 遍历结束”；截断样例返回非零退出状态和所在阶段。这是供读者核对的预期，未声称本文代码已在本机执行。普通 tar 允许的一些结束形式较宽松，因此成功遍历也不能替代业务侧的文件清单与可信长度记录。

怎样构造一个声明长度与正文不符的样例

可以在独立测试样例中，让一个普通条目的 Header.Size 声明为 8，实际只写入三个字节 abc。保留“完整头部加三个正文字节”这段未完成的数据供读取，即可研究正文提前结束的行为；它不是可交付的生产归档。

读者应分别观察：Next 能否取得头部，正文读取拿到多少字节，以及返回错误是否属于 io.ErrUnexpectedEOF。不要把缓冲区自动补零当作修复：补出的字节并非原始文件内容，反而会掩盖截断。

同样要区分“短读”和“结束”。一次 Read 读得少不一定损坏，合法 Reader 可以分多次供给数据；问题是还欠字节时底层已经终止。读者扩展样例时，可比较分段供给的完整输入与真正被裁掉尾部的输入，而不是仅改变缓冲区大小。

生产端应怎样结束归档和压缩层

生产端应以准备写入的真实内容确定声明大小，并检查 WriteHeader、正文写入、tar.Writer.Close 的错误；使用 gzip 包裹时，再检查 gzip.Writer.Close，最后关闭底层文件。tar.Writer.Close 不会替你关闭它下面的文件。若写入过程中源文件仍被修改，事先取得的大小也可能不再对应实际内容。

“只加 defer Close”不足以保证成功：错误需要进入最终返回值；归档必须在收尾成功后才作为完成产物交付。建议先在独立暂存位置完成，成功后再按存储系统的发布语义使读者可见，避免消费者读到仍在写入中的文件。

把传输截断与格式错误分开处理

文件扩展名不是格式证明；把 gzip 字节直接传给 tar.Reader 也不是正确解码。对于 .tar.gz，gzip.Reader 与 tar.Reader 是两层读取对象，错误可能从外层传入。按照 gzip.Reader 文档，仅 Close 不会完成压缩校验，需要真正读至其 EOF。tar 到达结束标记，不保证 gzip 已经消费到自身结尾。

如果要继续消费 gzip 剩余数据，应先设定允许的解压字节数、超时与额外数据策略；达到人为限制必须报告“检查未完成”，不能伪装成正常 EOF。本文主例没有实现压缩包安全检查，也没有替读者执行这些操作。

修复后还需要留意哪些边界

能不能遇到 unexpected EOF 就继续下一个文件？

不应把损坏读取当成成功。Reader 的后续操作可能继续返回同一错误；即便已有部分正文，也只能按明确的恢复策略作为不完整数据隔离，不能直接发布为完整文件。

只有少一个结束标记一定能发现吗？

不能用单个错误保证检测所有截断。部分结束位置可能被读取器接受；需要结合可信的产物长度、内容摘要与预期文件清单。这是归档消费系统的设计建议，不代表本文示例进行了额外校验。

遍历器能直接用于解压上传文件吗？

不能。例子不创建归档内路径，不处理落盘权限、符号链接和覆盖策略；声明大小配额也不是解析头部扩展数据的完整资源隔离。加入解压功能前，应另行设计路径、总量、超时与暂存文件清理规则。

排查时保留原始产物，先定位读取阶段，再回到产出和交付边界修复。重新取得完整归档，比把错误强行改成成功更能保持文件内容可信。