Go archive/tar Reader.Next 怎样读取 PAX 扩展头

读取 tar 归档时，通常不需要自己寻找 PAX 的 TypeXHeader 数据块。archive/tar.Reader.Next 会把作用于下一个文件的 PAX 扩展头透明处理，再返回一个普通文件的 *tar.Header；自定义键值可以从这个 Header 的 PAXRecords 读取，标准键则会同步修正 Name、Size 和时间等字段。

因此正确的思路是“遍历普通条目，读取 Header.PAXRecords”，而不是把 PAX 元数据当成一个需要单独消费的文件。官方文档地址：https://pkg.go.dev/archive/tar#Reader.Next

先区分 PAX 元数据条目和普通文件条目

PAX 用类型为 'x' 的扩展头保存只对下一个文件生效的键值记录。Reader.Next 内部会读取它、解析记录，然后继续寻找真正的文件条目，所以外部循环一般不会看到这个中间条目。读取到的 Header 仍然对应文件本身，当前文件内容继续由同一个 Reader 提供。

下面的循环只关注三个结果：返回文件 Header、遇到归档结束的 io.EOF，以及遇到格式错误时保留原始错误。

package main

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

func walkTar(r io.Reader) error {
	// Reader 以流式方式遍历归档，不需要把全部内容读进内存。
	tr := tar.NewReader(r)
	for {
		hdr, err := tr.Next()
		if errors.Is(err, io.EOF) {
			return nil // 两个归档结束块表示没有更多条目。
		}
		if err != nil {
			return fmt.Errorf("读取 tar 条目: %w", err)
		}

		// 这里只处理普通条目的 Header，PAX 扩展头已由 Next 合并。
		fmt.Printf("%s size=%d format=%s\\n", hdr.Name, hdr.Size, hdr.Format)
		if _, err := io.Copy(io.Discard, tr); err != nil {
			return fmt.Errorf("跳过 %q 的内容: %w", hdr.Name, err)
		}
	}
}

从返回的 Header 读取 PAXRecords

自定义 PAX 键建议使用大写厂商命名空间，例如 GOLANG.pkg.version。拿到普通文件 Header 后，可以直接查表；而 path、size、mtime 这类标准记录还会参与对 Name、Size、ModTime 的修正，不能只看原始 USTAR 字段。

func readPAXMetadata(tr *tar.Reader) error {
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			return nil // 归档正常结束。
		}
		if err != nil {
			return fmt.Errorf("读取 Header: %w", err)
		}

		// 自定义记录仍保留在 PAXRecords 中，缺失时不要当成空字符串业务值。
		version, ok := hdr.PAXRecords["GOLANG.pkg.version"]
		if ok {
			fmt.Printf("%s version=%s\\n", hdr.Name, version)
		}
		// Size 与 ModTime 可能已由 PAX 的标准键修正。
		fmt.Printf("name=%s size=%d mtime=%s\\n", hdr.Name, hdr.Size, hdr.ModTime.Format(time.RFC3339Nano))

		// 当前条目数据由 Reader 继续提供，消费完后再调用 Next。
		if _, err := io.Copy(io.Discard, tr); err != nil {
			return fmt.Errorf("读取 %q 内容: %w", hdr.Name, err)
		}
	}
}

实际代码需要补上 time 导入。这里的重点不是记住某几个键，而是区分两类信息：标准键会影响 Header 的语义字段；未被标准库映射的用户键继续以字符串键值保存在 PAXRecords 中。扩展属性使用 SCHILY.xattr. 命名空间时，还会映射到 Header.Xattrs。

按 EOF、解析错误和全局头分类处理

普通扩展头与全局扩展头的行为不同。TypeXHeader 只影响紧随其后的文件，TypeXGlobalHeader 描述后续条目的全局信息；当前标准库会解析并返回这个全局头对应的特殊 Header，但不会把全局状态自动持久化到之后的每一个文件条目。调用方不能把它当作普通文件内容。

错误也要分开：io.EOF 是正常结束；tar.ErrHeader 代表头部或 PAX 记录无法解析；其他底层读取错误则需要继续保留原始错误上下文。

func classifyNextError(err error) string {
	// 先区分正常结束，再把格式错误和底层 I/O 错误交给不同处理路径。
	switch {
	case errors.Is(err, io.EOF):
		return "archive-end"
	case errors.Is(err, tar.ErrHeader):
		return "invalid-tar-or-pax-header"
	default:
		return "underlying-reader-error"
	}
}

把元数据读取封装成稳定遍历函数

如果上层只需要文件名、大小和少量业务扩展字段，可以在一个函数中完成边界处理，把全局头和未知 PAX 键的策略明确下来。调用方得到的是干净的普通条目数据，不必了解 tar 的物理块布局。

type EntryMeta struct {
	Name    string
	Size    int64
	Version string
}

func readEntries(r io.Reader) ([]EntryMeta, error) {
	// 输出只保留业务需要的字段，避免把 Header 的生命周期泄露给调用方。
	tr := tar.NewReader(r)
	var entries []EntryMeta
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			return entries, nil
		}
		if err != nil {
			return nil, fmt.Errorf("遍历归档: %w", err)
		}

		// 不把全局扩展头误当成可下载文件；普通文件才进入业务结果。
		if hdr.Typeflag == tar.TypeXGlobalHeader {
			continue
		}
		version := hdr.PAXRecords["GOLANG.pkg.version"]
		entries = append(entries, EntryMeta{Name: hdr.Name, Size: hdr.Size, Version: version})
		if _, err := io.Copy(io.Discard, tr); err != nil {
			return nil, fmt.Errorf("消费 %q: %w", hdr.Name, err)
		}
	}
}

这个封装的核心是保持调用顺序：先判断 Next 的错误，再读取 Header 和 PAXRecords，最后消费当前条目内容，之后才进入下一次 Next。这样既不会重复读取 PAX 元数据，也不会让上一个文件剩余的字节干扰下一个条目。

常见问题

为什么循环里看不到 TypeXHeader？

作用于下一个文件的 PAX 扩展头由 Reader.Next 内部解析并合并，外部看到的是合并后的文件 Header。只有需要处理全局扩展头等特殊情况时，才要额外判断返回 Header 的类型。

标准 PAX 键只能从 PAXRecords 读取吗？

不只如此。标准库会把已知键映射到 Name、Size、ModTime 等字段，同时保留 PAX 记录表；业务代码应以修正后的 Header 字段作为文件语义，以 PAXRecords 读取自定义键。

遇到 io.EOF 还要继续调用 Next 吗？

不需要。io.EOF 表示归档遍历正常结束；继续调用只会重复得到结束状态，应该直接返回成功或结束当前任务。

总结

Reader.Next 已经替调用方处理了普通 PAX 扩展头。遍历时直接接收文件 Header，从 PAXRecords 读取自定义键，并使用被 PAX 修正后的标准字段；遇到 io.EOF 正常收尾，遇到 ErrHeader 单独归类，遇到 TypeXGlobalHeader 则不要误当成普通文件。把这几个边界固定下来，就能稳定读取带扩展元数据的 tar 归档。