Go archive/tar.Reader.Next 遇到 PAX 扩展时怎么判断真实文件头：遍历顺序与错误恢复

用 Go 解包带长文件名或扩展属性的 tar 文件时，业务代码通常只需要处理真正的文件条目，不需要把 PAX 扩展头当成一个文件。archive/tar.Reader.Next 会在内部读取并合并这些扩展记录，然后返回可读取数据的真实 Header；循环里仍要处理当前数据、区分 io.EOF 与其他错误。

判断“真实文件头”的关键不是自己跳过一个名为 PAX 的条目，而是只把 Next 返回的成功 Header 交给业务处理，并在每次前进前收尽当前文件数据。

先看清 Reader.Next 返回的对象

tar 文件的物理布局里可能出现 PAX 全局扩展头、局部扩展头和普通文件头。它们都是归档流中的记录，但 archive/tar 的公开迭代接口把扩展信息合并到了目标 Header 的 Name、Size、ModTime 或 PAXRecords 中。业务层不应该根据名称猜测“这个头是否真实”。

真正可靠的边界是 Next 的返回值：成功返回的 Header 就是下一项可处理的条目，io.EOF 表示整个归档结束，其他错误则表示当前条目不能按正常路径继续。

用一个循环把扩展头和文件数据分开

下面的代码故意只保留三个业务节点：Reader.Next 取得头部，Header.Size 约束读取范围，io.Copy 消费文件内容。PAX 记录由包内部完成解析，循环不需要额外写“跳过 PAX”分支。

tr := tar.NewReader(src)
for {
    hdr, err := tr.Next()
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return fmt.Errorf("read tar header: %w", err)
    }

    if hdr.Typeflag == tar.TypeDir {
        continue
    }
    if _, err := io.Copy(dst, tr); err != nil {
        return fmt.Errorf("copy %q: %w", hdr.Name, err)
    }
}

io.Copy 读取的是当前 Header.Size 对应的数据区，读到该条目末尾后返回。下一次调用 Reader.Next 会自动丢弃当前文件尚未读取的剩余数据，所以即使业务只取前几 KB，也不能把底层流停在中间就直接把它当作下一个文件。

为什么 PAX 扩展不会变成多余文件

以长文件名为例，PAX 局部扩展里保存的是键值记录，随后才是目标文件头。Reader.Next 先处理扩展记录，再把有效字段放进后续返回的 Header；因此业务拿到的 hdr.Name 应直接作为当前文件名使用，而不是再扫描一遍流寻找“下一个头”。

如果需要审计扩展信息，可以检查 Header.PAXRecords。这个字段适合记录供应方写入的额外属性，但不要把它当作每个归档都必有的字段：普通 USTAR 头可能没有用户自定义记录。

错误恢复要分三种情况

io.EOF 只是正常收尾

循环遇到 io.EOF 后退出即可。不要把它记录成“损坏文件”，也不要在 EOF 后再次调用 Read 期待拿到下一个条目。

解析错误不能靠继续 Next 掩盖

校验和、记录长度或格式不合法时，Next 可能直接返回错误。此时当前游标是否还能安全恢复取决于错误位置，通用解包器应保留文件名、错误文本和已处理条目数，然后终止本次归档，避免把后续字节误认成文件内容。

ErrInsecurePath 要单独记录

当 GODEBUG=tarinsecurepath=0 时，非本地路径可能让 Next 同时返回头部和 ErrInsecurePath。这不是 PAX 专属错误。若产品不接受 ../ 或绝对路径，应拒绝该条目；若确实要兼容旧归档，也要先把路径规范化到目标目录内再写盘。

实际排查时看这几个证据

• 打印 hdr.Name、hdr.Size 和 hdr.Format，确认长名称被合并后只出现一次。
• 记录每轮 Reader.Next 成功次数，确认异常发生在头部解析还是内容复制。
• 写盘前用本地路径校验限制目标目录，不能因为 ErrInsecurePath 被忽略就直接拼接文件名。

相关问题

调用 Next 前必须把当前文件读完吗？

不必由业务代码手动读完；文档规定下一次 Next 会自动丢弃当前文件剩余数据。但如果需要校验内容或落盘，就应让 io.Copy 正常消费当前条目。

PAXRecords 为空是否说明文件头无效？

不是。它只是扩展记录集合，普通 tar 条目完全可能为空。是否有效应看 Next 的错误和返回的基本字段。

最后核对

把 tar 解包逻辑写成“Reader.Next 获取成功头部、按 Header.Size 读取、对 io.EOF 收尾、对其他错误停下”的小循环，PAX 扩展就不会污染业务层的文件列表；路径风险则在写盘前单独处理。