Go archive/tar Header.Format 怎样判断归档头格式

我在处理 tar 归档时，最容易误判的一点是把 Header.Format 当成“文件头里一定存在的格式标签”。在 Go 的 archive/tar 中，它是读取器根据当前条目做出的尽力判断；遇到宽松兼容或非标准归档时，结果可能是 FormatUnknown。因此，正确写法是先读取格式，再把它当作兼容性线索，而不是把未知值直接当成损坏。

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

判断 tar 格式时，优先看 Header.Format，再结合条目的字段能力和接收方约束做决定；需要重新打包时，明确设置 FormatPAX 或其他目标格式，不要只复制原 Header 后交给 Writer 猜。

先明确 Header.Format 表示什么

archive/tar 把常见格式抽象成 FormatUSTAR、FormatPAX、FormatGNU 和 FormatUnknown。其中 USTAR 兼容面较广，但字符串长度、非 ASCII 名称和文件大小都有边界；PAX 用扩展记录补足这些能力；GNU 格式支持更多历史扩展，但不一定是所有接收方的首选。

读条目时，格式和名称、大小属于同一份元数据生命周期：先由 Reader.Next 产生 Header，再由业务代码决定是否读取内容。不要在没有成功拿到 Header 时访问 Format，也不要把 FormatUnknown 自动改写成某个已知格式。

按能力比较 USTAR、PAX 与 GNU

我的经验是先问“接收方需要什么”，再谈格式名称。只要要保存 UTF-8 长文件名、亚秒级时间或稀疏文件信息，USTAR 往往不够；PAX 通常是更稳妥的扩展方案。若对端明确只识别 GNU 扩展，才考虑 FormatGNU。Go 文档也建议在没有特殊兼容要求时优先选择 PAX。

特别要注意：Go 的 Writer 目前不支持写入稀疏文件。能读取某种格式，不代表 Writer 能原样重建该格式的全部语义。

在 Reader.Next 后读取并记录格式

下面的示例只关心条目元数据和格式判断。对于未知格式，我会保留名称与大小，并把它交给上层策略；示例没有把说明性的输出当成实际运行结果。

package main

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

func inspectTar(r io.Reader) error {
	tr := tar.NewReader(r)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			return nil // 读到归档尾部，正常结束遍历。
		}
		if err != nil {
			return fmt.Errorf("读取 tar 条目失败: %w", err) // 保留原始错误，便于上层判断。
		}

		format := hdr.Format.String()
		if hdr.Format == tar.FormatUnknown {
			format = "unknown" // 未知格式不等于立刻损坏，先保留元数据。
		}
		fmt.Printf("name=%q size=%d format=%s\\n", hdr.Name, hdr.Size, format)
		// 进入下一轮 Next 前，当前条目剩余数据会由 Reader 自动丢弃。
	}
}

这里的关键不是打印格式，而是给后续策略留出边界：如果目标只是列目录，记录 Name 与 Format 就够了；如果要重打包，则还要读取业务关心的字段，并为输出格式重新创建 Header。

重新写入时显式设定格式

直接把 Reader.Next 返回的 Header 原样交给 Writer，短期看很方便，但复制了不需要的字段，也把格式选择交给了隐式规则。更稳的办法是用新 Header 复制必要信息，并根据接收方约束显式指定 FormatPAX。

func writeEntry(tw *tar.Writer, src *tar.Header, body io.Reader) error {
	// 只复制业务需要的字段，避免把输入归档的隐含状态原样带出。
	out := &tar.Header{
		Name:    src.Name,
		Mode:    src.Mode,
		Size:    src.Size,
		ModTime: src.ModTime,
		Format:  tar.FormatPAX, // 需要长名称或扩展时间时明确选择 PAX。
	}
	if err := tw.WriteHeader(out); err != nil {
		return fmt.Errorf("写入 tar 头失败: %w", err) // 头写入失败时不要继续写正文。
	}
	if _, err := io.Copy(tw, body); err != nil {
		return fmt.Errorf("写入 tar 内容失败: %w", err) // 内容错误交给调用方决定是否放弃归档。
	}
	return nil
}

如果接收方只支持传统 USTAR，应该把选择写成配置并在写 Header 时处理超长字段错误，而不是默默降级。对 GNU 专有接收方同理，使用 FormatGNU 前要先确认对端要求。

处理未知格式与资源边界

FormatUnknown 更适合作为“需要谨慎处理”的信号。可以继续读取条目并记录原始名称，也可以在严格归档策略中拒绝它；选择哪一种取决于业务是否允许宽松兼容。无论采用哪种策略，都要检查 Next、Read、WriteHeader 和 Close 的错误。

另一个容易遗漏的点是，Next 会推进到下一条，并自动丢弃当前条目的剩余数据；如果当前条目要保存内容，就必须在下一次 Next 前读完或复制完。重新写入时也不要复用旧的 Header 指针，创建新对象更容易把格式和字段边界说清楚。

相关问题

Header.Format 为什么可能是 FormatUnknown？ Reader 对部分不完全合规的归档采取宽松读取，无法可靠归类时就会返回未知格式。

读取到 FormatPAX 就一定要手动解析扩展头吗？ 通常不需要。archive/tar 会把常见 PAX 信息映射到 Header；只有业务要处理自定义 PAXRecords 时才读取对应字段。

什么时候不应该强制使用 FormatPAX？ 当接收方明确只支持 USTAR 或 GNU 时，不要只因为 PAX 能力更强就强制选择；应按对端兼容性和字段限制做决定。