Go 读取稀疏 tar 文件大小异常怎么办

我排查 tar 包时遇到过一个很容易误判的现象：归档文件本身并不大，但 archive/tar 返回的 Header.Size 却非常大。多数时候这不是 Go 把长度读错了，而是条目本来就是稀疏文件。Header.Size 表示逻辑文件大小，稀疏空洞在 Reader.Read 中会以 NUL 字节读出来；如果直接 io.ReadAll 或写进内存缓冲区，内存自然会按逻辑大小增长。

官方地址：https://pkg.go.dev/archive/tar

先把“逻辑大小、归档实际载荷、程序输出字节数”分开，再决定是只看元数据还是流式读取内容。不要按 tar 文件的物理大小去推断 Header.Size，也不要手工按物理载荷猜下一个条目的偏移。

先分清逻辑大小与归档占用

稀疏文件通常由少量真实数据块和一段或多段空洞组成。空洞不需要在归档中保存同样多的非零字节，但它仍然属于文件的逻辑地址空间。因此同一个条目至少要看三件事：

Go 的 tar 包支持 GNU 和 PAX 中的稀疏文件表示；文档把 Header.Size 定义为逻辑文件大小，并说明稀疏区域读取时会返回 NUL。也就是说，大小看起来“异常”并不等于头部损坏，先看 hdr.Format 和 hdr.Typeflag 更稳妥。

让 Reader 按条目边界输出

如果任务只是列出文件名、类型和逻辑长度，读取完 Next 返回的头部就够了，不要为了“确认大小”把内容全部读进内存。需要导出内容时，把目标设计成流式写入，并把 Header.Size 当成当前条目的逻辑上限：

package main

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

func copyEntry(tr *tar.Reader, dst io.Writer, hdr *tar.Header, maxSize int64) error {
    // 先限制业务允许的逻辑大小，避免异常头部拖垮内存或磁盘。
    if hdr.Size  maxSize {
        return fmt.Errorf("条目 %q 的逻辑大小 %d 超过上限", hdr.Name, hdr.Size)
    }

    // Reader 会把稀疏空洞作为 NUL 返回；io.Copy 仍然按逻辑内容流式转发。
    n, err := io.Copy(dst, io.LimitReader(tr, hdr.Size))
    if err != nil {
        return fmt.Errorf("读取条目 %q 失败: %w", hdr.Name, err)
    }
    // 读不到 Header.Size 通常意味着归档被截断，不能静默当成成功。
    if n != hdr.Size {
        return fmt.Errorf("条目 %q 内容不完整: got=%d want=%d", hdr.Name, n, hdr.Size)
    }
    return nil
}

这个函数没有把当前条目装入 []byte，但它仍可能把空洞写成显式的 NUL，所以输出目标的物理占用不一定保留原归档的稀疏特性。若只是扫描元数据，直接循环调用 Next；若要保留稀疏布局，需要目标文件和专门的稀疏写入策略，不能指望普通 io.Writer 自动恢复空洞。

另一个边界是特殊条目：目录、软链接等并不一定有可读的数据体，不能只看 Header.Size 就对所有条目执行同一套内容复制逻辑。先按 Typeflag 分流，再决定是否创建目标文件。

把 Next 的自动丢弃当成偏移契约

tar.Reader 是顺序读取器。调用 Next 时，如果上一个条目还有未读数据，包会自动丢弃剩余部分，然后定位到下一个条目。这里的“剩余部分”按当前条目的逻辑边界处理，调用方不需要也不应该根据归档文件的物理长度自行 Seek。

因此，下面两种写法的意图不同：

• 只做目录扫描：读取 hdr.Name、hdr.Size、hdr.Typeflag，直接进入下一轮。
• 需要完整内容：复制后比较实际字节数与 hdr.Size，确认没有截断，再进入下一轮。

如果你只读取了前一部分内容就返回，后续仍可调用 Next；但这不代表前一部分已经是完整文件。真正需要完整性的场景，应该在放弃当前条目前记录“未消费完”，或者让上层把它视为失败。

大小异常时按这张表排查

两个容易混淆的问题

为什么 Header.Size 比 tar 文件还大？ 因为它描述的是恢复后的逻辑文件长度；稀疏文件的空洞可以不占同等大小的归档载荷。

只调用 Next 会不会留下偏移问题？ 不会。文档约定 Next 会自动丢弃当前条目的未读数据。真正危险的是调用方绕开 Reader，按自己的物理大小计算偏移，或者把未读完的条目误报为完整读取。

我现在处理这类包时，会把逻辑大小、实际复制字节数和输出文件的物理占用分别记录。这样既能保留稀疏 tar 的真实语义，也不会因为一个看似异常的数字把问题错误归因到 Go 的读取器。