Go archive/tar Reader.Next 读取稀疏文件怎么验收：PAX 扩展与文件偏移边界

排查归档恢复问题时，最容易误判的是“读取成功”。archive/tar 能把 PAX 稀疏文件交给 Reader，但验收不能只看 Reader.Next 返回了没有：当前条目的逻辑长度、空洞位置、下一个条目的起点，以及非本地路径错误，都要分别核对。

可靠的做法是让 Reader.Next 负责逐项推进，让 Header.Size 定义当前数据边界，再按预期的稀疏布局检查读出的 NUL 字节；遇到 io.EOF 才结束整个归档。

先把 Reader.Next 的边界说清楚

tar.NewReader 接收一个 io.Reader，返回顺序读取归档的 *tar.Reader。第一次调用 Reader.Next 取得第一个条目；随后对同一个 reader 调用 Read，读到的是当前条目的数据，而不是整个 tar 流。

当前条目的可读长度由 Header.Size 给出。若本次没有把它读完，下一次 Reader.Next 会自动跳过剩余数据再解析下一个头。这一点很适合做顺序扫描，但也意味着“我少读了一段，下一项还能不能对齐”不能靠猜，要用下一项的名称和尺寸验收。

用一个顺序扫描器记录实际消费量

下面的扫描器只把普通文件的内容读入计数器，不把整个条目塞进内存。它保留了三个检查点：进入条目时记录 Header.Size，读取结束时比对实际字节数，下一次 Reader.Next 时再确认顺序。

package main

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

func scan(path string) error {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close()

    tr := tar.NewReader(f)
    for {
        h, err := tr.Next()
        if errors.Is(err, io.EOF) {
            return nil
        }
        if err != nil {
            return fmt.Errorf("Reader.Next: %w", err)
        }
        if h.Typeflag != tar.TypeReg && h.Typeflag != tar.TypeGNUSparse {
            continue
        }

        n, err := io.Copy(io.Discard, tr)
        if err != nil {
            return fmt.Errorf("read %q: %w", h.Name, err)
        }
        if n != h.Size {
            return fmt.Errorf("size mismatch for %q: got %d want %d", h.Name, n, h.Size)
        }
        fmt.Printf("%s: %d bytes\\n", h.Name, n)
    }
}

这里的 io.Copy 直到当前条目返回 io.EOF 才结束，下一轮才会进入新的 Reader.Next。对普通文件，这个比对通常直接成立；对稀疏文件，读出的仍是逻辑文件长度，空洞不会让 n 变小。

PAXRecords 和稀疏空洞如何落到 Read 结果

PAX 是扩展头格式，Go 会把与后续条目有关的键值放进 Header.PAXRecords。稀疏布局可能使用 GNU.sparse.map 等键描述真实数据区间；当 Header.Typeflag 表明条目是 TypeGNUSparse 时，Reader.Read 会把未存储的空洞读成 NUL 字节（图中标为 NUL-bytes）。

因此，恢复程序若要写回普通文件，可以直接顺序读取逻辑内容；若要保留磁盘上的稀疏形态，则还要自己依据布局做定位写入，不能因为读到了 NUL 字节就断言“归档里真的存了同样数量的零”。本文的验收重点是逻辑内容与顺序，不是判断文件系统是否继续使用稀疏分配。

四个检查点能抓住偏移错位

检查条目类型和名称

先记录 h.Name、h.Typeflag 和 h.Size。目录、符号链接等特殊条目通常没有可读数据，调用 Read 得到 io.EOF 是正常结果，不能按普通文件比较长度。

检查 PAXRecords 是否符合预期

如果输入由 GNU tar 生成，稀疏记录可能位于 PAX 扩展里。把 PAXRecords 打印到调试日志前要限制来源和长度，生产环境不要无条件输出用户可控的扩展键值。

检查当前条目的逻辑长度

用 io.Copy 或 io.CopyN 读取到当前条目结束，再将计数与 Header.Size 比对。稀疏空洞被返回为 NUL 字节，所以逻辑长度仍应和 Header.Size 对齐。

检查下一项，而不是只检查当前项

至少准备一个包含两个条目的归档。第一项故意只读一部分，然后直接调用 Reader.Next，确认第二项的 Name 和 Size 正确。这能验证库自动丢弃剩余数据的行为，也能抓到自定义缓冲层提前吞读的问题。

路径安全错误不要被吞掉

当前 Go 文档说明，在 GODEBUG=tarinsecurepath=0 时，Reader.Next 遇到非本地路径可能返回带有 ErrInsecurePath 的结果。是否继续使用返回的 header，要由应用的解包策略决定；面向用户上传归档的服务通常应拒绝并记录路径，而不是为了“继续解压”直接忽略所有错误。

h, err := tr.Next()
if err != nil && !errors.Is(err, tar.ErrInsecurePath) {
    return fmt.Errorf("next entry: %w", err)
}
if h == nil {
    return fmt.Errorf("missing header")
}
// 只有在策略允许时，才继续检查 h.Name 是否落在目标目录内。

这段判断不等于完整的路径防护。落盘前仍应使用明确的目标目录、校验本地路径并防止符号链接逃逸；ErrInsecurePath 只是归档条目安全信号之一。

常见问题

Reader.Next 后不把当前文件读完可以吗？

可以。下一次 Reader.Next 会自动丢弃当前条目剩余数据，但如果你需要统计完整内容或校验摘要，就必须在推进前读完它。

稀疏文件读出的 NUL 字节来自哪里？

它们代表稀疏布局中的空洞，是读取器为了呈现逻辑文件内容返回的零字节，不代表归档一定逐字节保存了这些零。

为什么 Header.Size 对了，恢复后的文件仍然不对？

尺寸只证明逻辑长度一致。还要核对条目顺序、内容摘要、PAX 稀疏布局以及写回时是否正确处理了路径和文件类型。

把验收结果写成可复查证据

一个合格的读取测试至少保留条目名称、类型、Header.Size、实际读取量、PAX 记录是否存在、下一条目名称，以及最终的 io.EOF。这样出现偏移错位时，能判断是当前条目少读、PAX 解析异常，还是归档本身的路径安全错误，而不是只看到一句“解压失败”。