Go tar.Reader.Next 怎样逐个读取归档文件

Go 读取 tar 归档时，核心循环是“调用 tar.NewReader 创建读取器，反复调用 Reader.Next 获取下一个 Header，再把当前 Reader 当作文件内容读取”。当 Next 返回 io.EOF，表示归档已经结束；其他错误都应该保留并交给调用方处理。

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

把 Header 当作当前条目的安全边界：先判断名称、类型和大小，再读取内容；不要把“没有更多条目”和“归档损坏”混成同一种结果。

• 资产：当前条目的名称、类型、大小和内容。
• 风险：路径穿越、超大条目、未消费完的内容和格式错误。
• 控制：显式处理 io.EOF、检查 Header，并设置业务层资源上限。

先看清 Reader、Header 和当前内容

tar.Reader 对归档提供顺序访问。每次 Next 成功返回一个 *tar.Header，随后同一个读取器只对应这个条目的数据区；Header.Size 描述逻辑内容长度。目录、符号链接等条目可能没有可读取的数据体，因此不能只用“读到多少字节”判断条目类型。

可以把它记成一个稳定的关系：Next 负责切换当前条目并交付元数据，Read 或 io.Copy 负责消费当前条目的数据。读取完当前文件后，再调用 Next 才会继续寻找下一个条目。

用 Next 循环读取每个文件

func listTar(r io.Reader, w io.Writer) error {
    // Reader 保留归档的顺序，当前条目由 Next 返回的 Header 描述。
    tr := tar.NewReader(r)
    for {
        hdr, err := tr.Next()
        if err == io.EOF {
            // EOF 只表示归档正常读完，不是一个需要上报的故障。
            return nil
        }
        if err != nil {
            // 头部损坏、校验失败或不安全路径等错误不能静默跳过。
            return fmt.Errorf("读取 tar 条目失败: %w", err)
        }

        // 先查看元数据，再决定目录、链接和普通文件的处理策略。
        fmt.Fprintf(w, "%s %d %c\\n", hdr.Name, hdr.Size, hdr.Typeflag)
        if hdr.Typeflag == tar.TypeDir {
            continue
        }

        // 消费当前数据区，避免把未读内容留给下一次 Next。
        if _, err := io.Copy(io.Discard, tr); err != nil {
            return fmt.Errorf("读取 %q 内容失败: %w", hdr.Name, err)
        }
    }
}

这个示例只做目录列举和内容消费，不把归档文件写入磁盘。真正提取文件时，应在写入前检查 hdr.Name 和 hdr.Typeflag，并为单个条目与整个归档设置大小预算。

Next 会处理什么边界

下一次调用 Next 前，如果当前条目还有未读取的数据，标准库会自动丢弃当前条目的剩余部分以及必要的填充区，然后再解析后续头部。因此，调用方不必为了“跳过当前文件”手动读取到固定长度，但仍要认识到：跳过意味着内容不会进入你的校验、统计或落盘逻辑。

判断结束时只比较 err == io.EOF。如果返回了其他错误，即使同时拿到了一个部分头部，也应该按错误处理。读取当前内容时，io.Reader 允许一次只返回部分数据；使用 io.Copy 或正确处理 n 与 err，不要假定一次 Read 就能拿完 Header.Size 指定的字节。

把路径和大小纳入提取安全控制

归档读取本身不等于安全提取。尤其是把 hdr.Name 直接交给 filepath.Join 时，必须先确认它是本地相对路径，不能让绝对路径或包含父目录跳转的名称逃出目标目录。Go 的当前实现也会在特定 GODEBUG 配置下对非本地名称返回 ErrInsecurePath；应用仍应把路径检查作为自己的提取策略。

func safeTarget(root, name string) (string, error) {
    // 只允许本地相对路径，拒绝绝对路径和父目录跳转。
    if !filepath.IsLocal(name) {
        return "", fmt.Errorf("不安全的归档路径: %q", name)
    }

    // 清理后再拼接，目标目录由调用方固定，不接受归档内容覆盖 root。
    target := filepath.Join(root, filepath.Clean(name))
    return target, nil
}

大小控制也要放在资源边界内：Header.Size 是条目声明的逻辑大小，应用可以在读取前拒绝超过接口预算的普通文件；整个归档还应配合外层读取限制或配额统计。不要仅依赖扩展名判断类型，也不要因为条目名称看起来正常就跳过权限、链接和设备节点的处理策略。

常见问题

读到 io.EOF 后还要再调用 Next 吗？

不需要。io.EOF 表示归档输入已经结束，循环可以正常返回；如果是其他错误，应保留错误上下文。

当前文件没读完就调用 Next 会怎样？

Next 会丢弃当前条目的剩余数据和填充区，再定位到后续条目。这个行为适合明确跳过文件，但不适合需要完整校验或统计内容的场景。

tar.Reader 能直接读取 gzip 文件吗？

不能把 gzip 压缩层直接当作 tar 数据。应先建立对应的解压读取器，再把解压后的 io.Reader 交给 tar.NewReader；本文只讨论 tar 条目遍历本身。

实际使用时，可以用三句话复核：Next 得到当前条目，Read 消费当前内容，io.EOF 结束整个归档。再加上路径、类型和大小控制，读取逻辑才不会把归档格式问题扩大成文件系统风险。