archive/tar 读取超大文件头的内存控制

我在处理归档导入时，最容易踩的坑不是 tar.Reader 本身，而是把当前条目的内容先读进 bytes.Buffer，再决定要不要使用。只要归档里出现一个很大的文件，内存峰值就会跟着文件大小一起涨。

更稳妥的做法是把“文件头元数据”和“文件内容”分开：用 Next 获取 Header，只保存名称、大小、类型等必要字段；不需要落盘的 payload 直接用固定大小缓冲区消费，需要落盘的内容则边读边写。Go 官方地址：https://pkg.go.dev/archive/tar

超大 tar 条目的内存控制关键，不是限制 Header.Size，而是避免按它分配完整缓冲区；Header.Size 用来描述边界，真正的内存上限由你的读取缓冲区和业务对象决定。

先把 Header 和 payload 分开

archive/tar 是顺序读取器。调用 Next 后，返回的 Header 描述当前条目；随后从同一个 Reader 读取的内容才属于这个条目的 payload。Header.Size 表示当前条目可读取的数据量，并不意味着程序必须创建一个同样大小的字节切片。

如果业务只需要列出归档目录，可以在拿到头部后马上跳过普通文件内容；如果要计算摘要或统计字节数，也应该把 payload 送入流式消费者，而不是先拼成一个完整字符串。

用 Next 逐条读取需要的字段

下面这个函数只收集普通文件的名称和大小，目录、符号链接等特殊类型不读取内容。循环结束时用 io.EOF 判断归档自然结束，其他错误保留给调用方处理。

package main

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

type EntryMeta struct {
    Name string
    Size int64
}

func listRegularFiles(r io.Reader) ([]EntryMeta, error) {
    tr := tar.NewReader(r)
    var result []EntryMeta

    for {
        hdr, err := tr.Next()
        if err == io.EOF {
            // 到达两个零块表示的归档尾部，正常结束扫描。
            return result, nil
        }
        if err != nil {
            // 损坏头部、底层读取失败等错误不能当成正常结束。
            return nil, fmt.Errorf("read tar header: %w", err)
        }
        if !hdr.FileInfo().Mode().IsRegular() {
            // 目录和链接只有元数据，不需要把 payload 当作文件内容处理。
            continue
        }
        result = append(result, EntryMeta{Name: hdr.Name, Size: hdr.Size})
    }
}

这段代码的内存开销主要来自 result 中保存的元数据，而不是归档文件本身。若条目数量也可能很大，可以改成回调式处理，让每条元数据在消费后立即释放。

不需要保存内容时，用固定缓冲区消费

例如只想统计普通文件的字节数，或者要把内容交给哈希、压缩、扫描器等下游组件，可以使用 io.CopyBuffer。缓冲区大小是工程上的内存旋钮，但不应把它设置成 hdr.Size。

package main

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

func countPayload(r io.Reader) (int64, error) {
    tr := tar.NewReader(r)
    // 固定缓冲区只服务于当前条目，避免按 Header.Size 一次性分配。
    buf := make([]byte, 32*1024)
    var total int64

    for {
        hdr, err := tr.Next()
        if err == io.EOF {
            // 所有条目都处理完后返回累计字节数。
            return total, nil
        }
        if err != nil {
            // 读取过程中出现错误时，停止继续消费后续条目。
            return 0, fmt.Errorf("advance tar entry: %w", err)
        }
        if !hdr.FileInfo().Mode().IsRegular() {
            // 特殊条目没有需要统计的普通文件 payload。
            continue
        }
        n, err := io.CopyBuffer(io.Discard, tr, buf)
        if err != nil {
            // CopyBuffer 只使用固定缓冲区，错误仍需向上传递。
            return 0, fmt.Errorf("consume %q: %w", hdr.Name, err)
        }
        total += n
    }
}

Next 会处理当前条目剩余内容的边界，因此每轮只要把当前条目消费完，再进入下一轮即可。若下游本身支持 io.Writer，可以把 io.Discard 换成哈希器、文件或网络写入器。

需要落盘时也不要先组装完整内容

对需要保存的普通文件，可以根据头部元数据先做业务限制，再创建目标文件并直接复制。下面示例把单文件上限作为业务策略；它用于拒绝不允许的条目，不是让 archive/tar 预分配大内存。

func extractOne(dst io.Writer, tr *tar.Reader, hdr *tar.Header, maxSize int64) error {
    if hdr.Size  maxSize {
        // 先按业务上限拒绝过大的条目，避免无意义的落盘和后续处理。
        return fmt.Errorf("entry %q exceeds size policy", hdr.Name)
    }
    // 由调用方传入受控 Writer，读取和写入都保持流式进行。
    if _, err := io.Copy(dst, tr); err != nil {
        // 底层错误需要带上条目名称，便于定位归档中的具体对象。
        return fmt.Errorf("extract %q: %w", hdr.Name, err)
    }
    return nil
}

真实解包程序还要单独处理路径清理、符号链接、目标目录权限和临时文件提交。本文的重点是内存边界：不要把 hdr.Size 直接拿来创建 make([]byte, hdr.Size) 或调用 io.ReadAll。

几个容易误判的内存边界

还要注意“元数据集合”本身也会增长：如果归档包含数百万个小文件，把所有 EntryMeta 追加到切片同样会产生压力。此时可以边遍历边写数据库、发送消息，或者给收集器设置条目数量上限。

结语：把大小判断留在策略层

处理超大 tar 条目时，我会把职责拆成三层：tar.Reader 负责顺序读取，业务层根据 Header 做类型和大小决策，下游通过固定缓冲区或 Writer 消费 payload。这样即使单个文件很大，内存也不会被迫等比例放大。

相关问题：

• 为什么读取完一个 tar 条目后必须调用 Next 才能处理下一个条目？
• 目录和符号链接的 Header.Size 是否应该按普通文件处理？
• 归档条目很多时，怎样限制元数据切片自身的增长？
• 需要解包到磁盘时，怎样把路径安全和流式写入一起设计？

技术资料：https://go.dev/src/archive/tar/reader.go、https://pkg.go.dev/archive/tar