Go tar 读取 unexpected EOF 时怎样定位归档问题

我第一次遇到 Go 读取 tar 包报 unexpected EOF 时，直觉是把输入文件重新下载一遍。但真正有用的线索不在错误字符串本身，而在它出现于 Next() 还是当前条目的内容读取：前者可能是在丢弃上一条目剩余数据时发现输入被截断，后者则通常能直接落到某个 Header.Name。

官方文档：https://pkg.go.dev/archive/tar/

在 archive/tar 中，归档正常结束返回的是 io.EOF；如果某个条目声明了固定大小，但底层输入在数据读满前就结束，应该按 io.ErrUnexpectedEOF 处理。排查时要完整消费每个条目，并同时记录名称、声明大小和实际读取量。

先分清两个 EOF，不要把正常结束当成损坏

tar.Reader 是顺序读取器。调用 Next() 会取得下一个条目的头部，返回的 Header.Size 表示当前条目逻辑上还有多少字节可读。读到整个归档末尾时，Next() 返回 io.EOF，这是正常分支。

io.ErrUnexpectedEOF 的语义不同：输入在一个固定大小的数据结构中间结束了。对 tar 来说，常见表现是头部已经声明了条目大小，但底层文件、网络流或上游 Reader 实际提供的字节数不够。

先记住一个判断表：

旧写法为什么容易丢掉真正的条目线索

很多代码只循环调用 Next()，拿到头部后直接处理下一轮。这样做的问题是：Next() 会自动丢弃当前条目尚未读取的剩余数据。如果上游流正好在当前条目中间结束，错误可能被推迟到下一次 Next() 才出现，日志里只剩一句“读取 tar 失败”，很难知道是哪一个文件出了问题。

另一个常见误区是把所有 EOF 都当成可以忽略的结束信号。对普通 io.Reader 来说，io.EOF 表示没有更多输入；对有固定结构的数据，读到一半就结束则应保留 io.ErrUnexpectedEOF。错误判断要使用 errors.Is，因为上层通常会给错误增加条目名称和读取阶段。

用完整消费把错误落到具体条目

我现在会把“取得头部”和“消费条目”放在同一段循环里。这样每轮都能得到条目名、声明大小和实际读取量；如果复制内容失败，错误上下文就已经带上了定位信息。

package main

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

// scanTar 逐个消费条目，把截断位置保留在错误上下文中。
func scanTar(src io.Reader) error {
    tr := tar.NewReader(src)

    for {
        hdr, err := tr.Next()
        if errors.Is(err, io.EOF) {
            // 只有整个归档自然结束时，Next 才走这个成功分支。
            return nil
        }
        if err != nil {
            // Next 也可能在丢弃上一条目剩余内容时暴露底层截断。
            return fmt.Errorf("读取条目头失败: %w", err)
        }

        // io.Copy 会把当前条目的全部逻辑内容读完。
        n, err := io.Copy(io.Discard, tr)
        if err != nil {
            // n 与 Header.Size 一起说明实际读到了哪里。
            return fmt.Errorf("条目 %q 读取 %d/%d 字节失败: %w", hdr.Name, n, hdr.Size, err)
        }
        if n != hdr.Size {
            // 正常的普通条目应当读满 Header.Size，异常时不要静默继续。
            return fmt.Errorf("条目 %q 读取量异常: %d/%d 字节", hdr.Name, n, hdr.Size)
        }
    }
}

这个写法有两个关键点。第一，io.Copy 成功后返回的错误是 nil，不是 io.EOF；它把当前条目读完后，下一轮再由 Next() 判断归档是否结束。第二，n 是当前条目实际交给目标的字节数，和 hdr.Size 放在同一条日志里，比单纯记录错误文本有用得多。

怎样判断错误到底落在头部还是内容

建议把读取阶段分成三种情况记录：

1. 刚进入循环的 Next() 报错：如果上一轮没有完整读取条目内容，先检查上一条目；如果每轮都已经消费完，则再考虑头部字节不完整或归档尾部损坏。
2. io.Copy 报 io.ErrUnexpectedEOF：当前 hdr.Name 是第一定位线索，比较 n 与 hdr.Size 可以确认条目内容没有读满。
3. Next() 返回 io.EOF：不要把它包装成失败。它表示归档读取完成；若业务还要求校验文件数量或总大小，应在更上层单独做业务校验。

如果错误来自归档头部，通常拿不到一个可信的新 Header.Name。这时应保留上一个已知条目名、输入来源和读取阶段，避免把一个损坏的头部字段当成真实文件名继续处理。

用 errors.Is 保留底层语义，再决定是否重试

不要用字符串比较判断 unexpected EOF。上面的代码已经用 %w 包装错误，因此调用方可以继续使用 errors.Is 分类：

func handleTarError(err error) error {
    if err == nil {
        return nil
    }

    if errors.Is(err, io.ErrUnexpectedEOF) {
        // 固定结构未读满，优先检查下载、文件复制或上游流是否截断。
        return fmt.Errorf("tar 输入不完整，请检查源数据是否传输完毕: %w", err)
    }
    if errors.Is(err, io.EOF) {
        // 这里的 EOF 只代表调用链中的普通结束，不应自动标记归档损坏。
        return nil
    }

    // 其他错误可能是头部格式、权限或底层 I/O 问题，交给上层记录。
    return fmt.Errorf("tar 读取失败: %w", err)
}

是否重试取决于输入来源。如果是本地文件，先检查文件是否在生成或复制过程中被截断；如果是网络流，重试应重新获取完整输入，而不是对同一个已经到达 EOF 的 Reader 再调用一次。若上游支持长度或校验摘要，可以在传给 tar.NewReader 之前完成输入完整性确认，但这和 tar 解析本身是两个边界。

我会保留的排查清单

• 正常归档结束只认 Next() == io.EOF。
• 条目读取返回 io.ErrUnexpectedEOF 时，记录 Header.Name、Header.Size 和实际读取量。
• 每个条目都完整消费，避免让 Next() 代替业务代码悄悄丢弃剩余数据。
• 错误包装使用 %w，分类使用 errors.Is，不要比较错误字符串。
• 重新下载或重试前先确认上游输入确实可重新获取，别在同一个已耗尽的流上盲目重放。

相关问题

为什么 tar 读取到文件末尾不是每次都返回 unexpected EOF？

完整的 tar 归档有自己的结束边界，正常走到归档末尾时 Next() 返回 io.EOF。只有结构或条目数据在应有长度之前结束，才属于 unexpected EOF。

只调用 Next 不读取条目内容可以吗？

可以跳过内容，但定位问题时不建议这样做。Next() 会自动丢弃当前条目的剩余部分，完整消费更容易把错误归属到具体条目。

io.Copy 返回 io.EOF 需要特殊处理吗？

成功的 io.Copy 返回 nil，不会把正常源端 EOF 作为错误返回。若收到 io.ErrUnexpectedEOF 或其他错误，再按错误类型处理。

errors.Is 比比较字符串好在哪里？

上层可以用 %w 增加条目名称和读取阶段，同时保留 io.ErrUnexpectedEOF 的身份。调用方仍能稳定判断底层原因，而不依赖错误文本是否变化。