Go 怎样读取 tar 中的长路径元数据

读取 tar 中的长路径时，不建议自己扫描 512 字节头或把 PAX 扩展头当成普通文件。Go 的 archive/tar 会在 Reader.Next 中处理 PAX 记录：长路径通常已经合并到当前条目的 Header.Name，而没有映射成一等字段的键值仍可从 Header.PAXRecords 读取。

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

本文只讨论 PAX 头与 Reader 的读取顺序。重点是读取元数据，不是手工解包，也不把静态结构图当作运行截图。

先区分 PAX 扩展头和真正的文件条目

tar 是一串头部与数据块。PAX 的局部扩展头使用 TypeXHeader，它携带的键值只对紧随其后的条目有效；全局扩展头的作用范围更大。archive/tar 会透明处理这些扩展头，所以业务循环一般不需要判断“当前是不是 PAX 文件”。

对长路径来说，最重要的内置键是 path。读取完成后，应优先使用 Header.Name 作为当前条目的路径；它是库把基础头和 PAX 路径信息合并后的结果。自定义键，例如归档工具写入的注释或命名空间字段，则从 Header.PAXRecords 查看。

用 Reader.Next 顺序读出最终路径

Reader.Next 每调用一次就前进到下一个条目，并返回一个新的 Header。如果上一个条目的数据没有读完，库会自动丢弃剩余数据，因此循环只需要在需要时读取当前条目的内容；如果只关心元数据，可以不复制正文。

package main

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

func listTarMetadata(file *os.File) error {
	reader := tar.NewReader(file)
	for {
		header, err := reader.Next()
		if err == io.EOF {
			// 所有条目都处理完后，正常结束扫描。
			return nil
		}
		if err != nil {
			// PAX 解析或归档结构错误都要交给调用方处理。
			return err
		}

		// Name 是库合并扩展信息后的最终条目路径。
		fmt.Printf("name=%q format=%s size=%d\n", header.Name, header.Format, header.Size)
		if value, ok := header.PAXRecords["comment"]; ok {
			// 自定义 PAX 键值保留在 PAXRecords 中，不要从文件正文猜测。
			fmt.Printf("comment=%q\n", value)
		}
	}
}

这个循环不会把 PAX 扩展头打印成一个“额外文件”。如果归档中还有正文，下一次调用 Next 会自动跳过当前条目未读取的部分；如果要解出文件内容，再对当前的 reader 调用 io.Copy 或限制长度读取。

长路径看 Header.Name，自定义数据看 PAXRecords

不要把两个字段混成一个职责。Header.Name 适合用于归档目录、日志和后续提取决策；Header.PAXRecords 是扩展键值表，适合读取工具链附加的元数据。标准字段可能已经被 PAX 记录映射到 Name、时间或大小等字段，因此应用层通常不必再次解析 path 的字符串。

兼容边界：不要把所有长路径都归因于 PAX

tar 存在 USTAR、PAX 和 GNU 等格式。PAX 可以表达更长的名称，但 GNU 也有自己的长名称机制；因此“路径很长”只能说明基础头可能不够，不能据此反推出一定存在可读取的 PAX 记录。Header.Format 是 Reader.Next 给出的最佳判断，文档也提示非规范归档可能得到 FormatUnknown。

如果程序要做安全提取，还要单独检查 Header.Name 是否符合目标目录约束，并正确处理 ErrInsecurePath 等错误。读取出一个长路径，不等于允许把它直接拼接到本地目录。本文的代码只负责读取元数据，未把归档路径转换成文件系统路径。

常见问题

为什么循环里看不到 PAX 头对应的文件？因为 archive/tar 会透明处理局部 PAX 头，并把它应用到后续条目。

长路径应该读取 PAXRecords 的 path 吗？优先读取 Header.Name。它表达的是库已经合并后的最终路径；只有需要检查原始扩展键或自定义元数据时，才查看 PAXRecords。

Header.Format 是绝对准确的格式标签吗？不是。它是库根据头部做出的最佳判断，遇到宽松解析的非规范文件时可能是 FormatUnknown。

只读元数据时必须读完文件正文吗？不必。下一次 Next 会自动丢弃当前条目的剩余数据；只有要保存或分析正文时才读取当前 Reader。

速查：用 Reader.Next 逐条推进，长路径看 Header.Name，自定义 PAX 数据看 Header.PAXRecords，格式只作提示，并把路径安全检查放在元数据读取之后单独处理。