Go archive/tar FileHeader.PAXRecords 怎样读取扩展属性

如果你用 Go 读取 tar 包里的 PAX 扩展属性，核心入口就是 tar.Reader.Next() 返回的 *tar.Header：直接读取它的 PAXRecords 映射即可。这个映射为空时不代表读取失败，键不存在时也不能只靠字符串值判断。

官方文档：https://pkg.go.dev/archive/tar#Header

下面用一个只读示例把读取路径、键判断和边界条件串起来。文章中的图是原创结构说明图，不是终端截图或运行证据。

先理解 PAXRecords 在 Header 中的位置

tar 文件由一组条目组成，archive/tar 通过 Reader.Next 逐个返回条目头部。PAX 格式会用扩展头保存超出传统 tar 字段限制的键值记录，Go 会在读取时把这些记录整理到当前条目的 Header.PAXRecords 中。

PAXRecords 的类型是 map[string]string。自定义记录的键应使用自己的大写命名空间，例如 GOLANG.pkg.version；键和值都应是非空 UTF-8 字符串，键不能包含等号。

遍历 tar 条目并读取扩展属性

读取时不要把 PAX 扩展头当成需要单独消费的业务文件。调用 Next 后，当前条目的字段已经被组合到返回的 Header 中；随后可以读取 hdr.PAXRecords，再按需消费当前条目的正文。

package main

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

func main() {
	// 打开待读取的 tar 文件；defer 保证文件描述符及时关闭。
	f, err := os.Open("bundle.tar")
	if err != nil {
		panic(err)
	}
	defer f.Close()

	tr := tar.NewReader(f)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			// EOF 表示所有条目已经遍历完成，不是异常。
			break
		}
		if err != nil {
			panic(err)
		}

		fmt.Printf("name=%s format=%s\\n", hdr.Name, hdr.Format)
		for key, value := range hdr.PAXRecords {
			// PAXRecords 只保存当前 Header 的扩展键值。
			fmt.Printf("pax[%s]=%s\\n", key, value)
		}
	}
}

这里的关键点是 Next 的返回值。它会推进到下一个条目，并把当前条目的头部交给调用者；当前正文如果没有读完，下一次 Next 会自动丢弃剩余数据。因此读取扩展属性时，应该围绕每次返回的 hdr 处理，而不是在文件字节流里自己寻找 PAX 记录。

区分键存在、键缺失和空映射

从 map 读取一个键时，建议使用双值赋值。这样可以区分“键存在但值为空”和“键根本不存在”。在遵循规范的 PAX 记录中，键和值应为非空字符串，但读取外部归档时仍然应让判断逻辑清楚。

func readPAXValue(hdr *tar.Header, key string) (string, bool) {
	if hdr == nil {
		// 调用方传入空 Header 时，按键不存在处理。
		return "", false
	}
	value, ok := hdr.PAXRecords[key]
	if !ok {
		// ok=false 表示没有这个键，不等同于读取到空字符串。
		return "", false
	}
	return value, true
}

func printVersion(hdr *tar.Header) {
	value, ok := readPAXValue(hdr, "GOLANG.pkg.version")
	if !ok {
		fmt.Println("version: not present")
		return
	}
	// 只在键存在时解释字段，避免把缺失值当成默认版本。
	fmt.Println("version:", value)
}

同时要接受 PAXRecords 为 nil 的情况。遍历 nil map 是安全的，读取不存在的键也会得到零值和 false；如果业务需要区分“没有任何扩展记录”和“有记录但目标键缺失”，可以先判断 len(hdr.PAXRecords)。

处理命名空间与 Xattrs 等价关系

自定义 PAX 键不要随意使用通用名称，建议采用大写厂商或项目命名空间加点号的形式，例如 GOLANG.pkg.version。这样多个工具共同处理一个归档时，字段含义更容易保持稳定。

扩展属性还有一条容易混淆的关系：Header.Xattrs[key] 与 Header.PAXRecords["SCHILY.xattr."+key] 在语义上等价。旧代码可能还会使用 Xattrs，新代码读取统一的 PAX 记录时，应知道这个前缀映射，避免把同一份信息当成两套完全无关的数据。

读取与写入边界怎么判断

本文重点是读取，但排查结果时经常会遇到“我明明设置了 PAXRecords，为什么写回去不一样”。原因在于 Writer.WriteHeader 写出头部时，其他 Header 字段派生出的 PAX 记录可能优先于同名的 PAXRecords；而 Xattrs 的内容也优先于对应的 PAX 记录。读取到的值因此应理解为归档实际表达出来的结果，而不是某段写入代码的原样快照。

从 Reader.Next 得到 Header 后，如果要修改并重新写入，最好新建一个 Header，只复制确实需要保留的字段。官方文档也提醒，直接把读取到的 Header 大范围修改后交给 Writer，可能把不需要的格式细节一起带回去。

func copyPAXRecords(src map[string]string) map[string]string {
	// 复制 map，避免修改读取结果时影响调用方持有的 Header。
	dst := make(map[string]string, len(src))
	for key, value := range src {
		dst[key] = value
	}
	return dst
}

最后可以按下面的顺序排查：先确认 Next 没有返回错误，再确认条目确实是目标文件，然后判断 PAXRecords 是否为空，最后用双值 map 读取检查目标键。这样能把归档损坏、条目选择错误、键缺失和命名空间写错区分开。

常见问题

PAXRecords 为空是不是 tar 读取失败？

不一定。普通 USTAR 条目可以没有 PAX 扩展记录，读取是否失败要看 Next 返回的 error，而不是只看 map 是否为空。

为什么不能直接判断 value == ""？

因为 map 缺失键和存在空值都会得到空字符串。使用 value, ok := records[key] 才能保留存在性信息。

自定义 PAX 键应该怎样命名？

使用大写命名空间加点号，例如 GOLANG.pkg.version，并保证键和值是非空 UTF-8 字符串。

读取后为什么还要关注 Writer 的优先级？

如果程序还会把 Header 写回 tar，其他字段或 Xattrs 可能覆盖同名 PAX 记录；读取逻辑正确并不等于写回结果一定保持原样。