Go archive/tar.Reader.Next 读到 EOF 后如何判断归档是否正常结束

读取 tar 归档时，EOF 不是只有一种含义：当前条目的数据读完，通常是对 tr.Read 的正常结果；整个归档读完，才是 tr.Next 返回的 io.EOF。如果 Next 返回的是其他错误，就应该按解析失败或输入损坏处理，不能直接当成“没有更多文件”。

先分清两个 EOF：当前条目结束和归档结束

archive/tar 是流式读取器。调用 tar.NewReader 后，Reader.Next 负责移动到下一个归档条目，并返回这个条目的 Header；拿到 Header 后，读取器本身就代表当前文件的数据流。官方文档明确区分了两处边界：读取当前文件数据时，Read 会在条目末尾返回 io.EOF；移动到下一个条目时，Next 在整个归档末尾返回 io.EOF。

因此，常见的误判是把所有 io.EOF 都写成“归档结束”。更稳妥的思路是：Read 的 EOF 只结束当前条目，Next 的 EOF 才结束外层循环。

按 Next 的错误语义组织读取循环

读取循环应该先处理 Next，再处理当前 Header 的数据。只有 errors.Is(err, io.EOF) 成立时才跳出；其他错误直接返回给调用方。这样做的好处是，截断的头部、格式不正确的输入等问题不会被悄悄吞掉。

package main

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

func listEntries(src io.Reader) error {
    // tar.Reader 按顺序读取归档，不能把它当成随机访问目录。
    tr := tar.NewReader(src)
    for {
        header, err := tr.Next()
        if errors.Is(err, io.EOF) {
            // Next 的 EOF 表示整个归档已经正常读完。
            return nil
        }
        if err != nil {
            // 其他错误可能表示头部损坏或输入被截断，不能当成正常结束。
            return fmt.Errorf("读取 tar 条目失败: %w", err)
        }

        // Header 只描述当前条目；正文仍然要从 tr 中读出。
        fmt.Printf("%s (%d bytes)\n", header.Name, header.Size)
        if _, err := io.Copy(io.Discard, tr); err != nil {
            // 先消费当前条目，下一次 Next 才进入清晰的条目边界。
            return fmt.Errorf("读取 %q 的内容失败: %w", header.Name, err)
        }
    }
}

这里用 io.Copy(io.Discard, tr) 表示“当前条目的内容已经消费完”。实际业务可以把目标换成文件、哈希计算器或解码器，但错误分支仍要保留。若只需要列出名称，也可以不手动复制全部数据；下一次调用 Next 会自动丢弃当前条目尚未读取的数据并前进。不过显式消费更容易让代码表达“当前条目处理到哪里结束”。

为什么不能把 tr.Read 的 EOF 当成归档结束

拿到一个 Header 后，tr.Read 的职责是读这个条目的文件数据。它返回 io.EOF，说明这一段数据已经到达 Header.Size 对应的边界；此时归档后面可能还有更多条目。下面的函数展示了只读取一个条目时该如何判断：

func copyCurrentEntry(tr *tar.Reader, dst io.Writer) error {
    // 当前调用只负责一个 Header 对应的数据，不负责推进到下一条目。
    _, err := io.Copy(dst, tr)
    if err != nil {
        // io.Copy 把当前条目的正常 EOF 当成复制完成，不会把它当成失败。
        return fmt.Errorf("复制当前 tar 条目失败: %w", err)
    }
    return nil
}

如果自己手写 Read 循环，要记住特殊类型和普通文件的读取行为不同。普通文件读到条目末尾时会得到 EOF；目录、链接等没有普通文件正文的特殊条目，也可能直接返回 EOF。它们的名字、类型和大小应从 Header 读取，而不是等待正文里出现内容。

用 Header.Size 消费当前条目，再进入下一次 Next

Header.Name 是条目名称，Header.Size 是逻辑文件大小。对于需要落盘、计算摘要或解析文本的程序，应把当前 tr 当成受当前 Header 限定的数据源。读完后再进入下一次 Next，代码结构会更清晰。

func extractRegularFile(tr *tar.Reader, header *tar.Header, dst io.Writer) error {
    // 只按 Header 声明的条目范围处理当前数据，并保留条目名称用于错误上下文。
    if header.Typeflag != tar.TypeReg && header.Typeflag != tar.TypeRegA {
        // 目录、软链接等条目没有普通文件正文，不应按普通文件落盘。
        return nil
    }
    if _, err := io.Copy(dst, tr); err != nil {
        // 任何复制错误都要关联当前条目，便于定位是哪个文件失败。
        return fmt.Errorf("写入 %q 失败: %w", header.Name, err)
    }
    return nil
}

需要注意，Next 在前进时会自动丢弃当前条目剩余的数据。因此，代码不一定必须把每个条目全部复制出来，但必须明确这是“跳过剩余数据”，而不是验证文件内容完整。若业务要求校验字节数、哈希或格式，应在当前条目阶段完成。

遇到 ErrInsecurePath 或其他错误时怎样处理

除了 io.EOF，Next 还可能返回其他错误。Go 文档特别说明，在启用对应的 GODEBUG 行为时，遇到非本地文件名可能返回带有 Header 的 ErrInsecurePath。这不是归档结束，而是路径安全策略给出的提示。

func nextEntry(tr *tar.Reader) (*tar.Header, error) {
    header, err := tr.Next()
    if errors.Is(err, io.EOF) {
        // 只有 Next 的 EOF 才代表整个归档结束。
        return nil, io.EOF
    }
    if errors.Is(err, tar.ErrInsecurePath) {
        // 是否接受非本地名称必须由业务策略决定，不能无条件忽略安全提示。
        return header, fmt.Errorf("条目路径需要安全策略确认: %w", err)
    }
    if err != nil {
        // 解析错误、底层读取错误和截断输入都应保留给上层处理。
        return nil, fmt.Errorf("读取条目头失败: %w", err)
    }
    return header, nil
}

如果程序确实允许归档中的非本地名称，也应先定义清楚落盘目录、路径清理和覆盖策略，再决定是否忽略 ErrInsecurePath。不要因为看到 header 已经返回，就把这个错误误判成“可直接解压”。

排查 EOF 的快速对照表

常见问题

调用 tr.Next 前必须把当前文件全部读完吗？

不必须。下一次 Next 会自动丢弃当前条目剩余数据，但如果业务要校验内容、计算摘要或报告读取错误，就应该在当前条目阶段主动消费并处理。

tr.Read 返回 EOF 是否说明 tar 文件损坏？

通常不是。对当前条目而言，读到 EOF 是正常边界；需要区分的是 tr.Next 返回的非 EOF 错误。

为什么只列文件名时也要检查 Next 的 error？

因为文件名来自 Header，Header 解析本身可能失败。只判断 Header 是否为空，会把截断或格式错误输入隐藏掉。

可以忽略 ErrInsecurePath 吗？

只有在业务已经明确接受非本地条目名称，并有独立的路径清理和落盘策略时才考虑。它不是“没有更多文件”的信号。