Go tar.Header.Format 为什么会变成未知格式

tar.Header.Format 变成 tar.FormatUnknown，核心含义不是“这个条目一定读不了”，而是 archive/tar.Reader 已经尽力解析头部，却无法把它可靠归类为 USTAR、PAX 或 GNU。Reader.Next 的格式判断本来就是最佳努力；只要它返回的 err == nil，当前条目仍可按 Header.Size 继续读取。

真正无法接受的头部通常会让 Next 返回错误。例如头部校验和不成立时，标准库会返回 tar.ErrHeader，不会把失败伪装成一个可用的未知格式条目。因此排查时必须同时看 hdr.Format 和 err，不能只比较 Format。

触发现象：FormatUnknown 与读取失败不是一回事

FormatUnknown 是 tar.Format 的零值。它的 String 表示为 。这种状态常见于第三方工具生成的“基本可读、但不完全符合某个标准变体”的 tar 头部：字段能被宽松解析，格式特征却不足以通过严格归类。

读取前提：Reader 先检查头部是否足够可信

tar 的每个头部块是 512 字节。Go 标准库先解析并核对校验和，再根据 magic、version、trailer 等位置猜测格式。校验和失败时，内部格式判断直接得到未知值，随后 readHeader 返回 ErrHeader。这类情况没有可供业务继续使用的 Header。

如果校验和成立，Reader 会继续解析 V7 公共字段和各格式扩展字段。这里的解析器为了兼容历史归档，比格式规范更宽松，所以“字段能读出来”和“能严格证明是哪种格式”是两个不同判断。

识别阶段：哪些情况会把格式降为未知

以当前标准库实现为例，USTAR/PAX 头部虽然带有可识别 magic，但如果原始头部块含非 ASCII 字节，或者 size、mode、uid、gid、mtime、设备号等数值字段没有按要求以 NUL 结尾，Reader 会保留已解析字段，同时把 hdr.Format 降为 FormatUnknown。这说明归档生产方使用了非标准编码或宽松写法。

另一个兼容分支来自早期 Go 版本写出的少量异常 GNU 头部。当前 Reader 会尝试兼容解析其中被错误占用的时间与前缀区域；当它只能按旧行为恢复名称，却不能再把该头部视为合规 GNU 时，也会把 Format 标为未知。

这些例子并不是让业务代码去猜具体生产工具，而是帮助区分两层事实：Header 的常用字段可能可读，但格式标签不再适合作为强保证。对未知格式做兼容决策时，应基于实际需要的字段和下游格式要求，而不是仅凭文件扩展名。

判断门禁：按条目同时记录 Format 和错误

下面的最小诊断函数只观察 Reader 已返回的事实，不把未知格式直接当错误。它在 Next 失败时立即返回，在读取成功时记录条目名、类型、大小和格式：

package main

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

func inspectTar(r io.Reader) error {
	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)
		}

		if hdr.Format == tar.FormatUnknown {
			// 中文注释：未知格式是分类不确定，不等于当前条目不可读
			fmt.Printf("未知格式 name=%q type=%c size=%d\n",
				hdr.Name, hdr.Typeflag, hdr.Size)
			continue
		}

		fmt.Printf("格式=%v name=%q size=%d\n",
			hdr.Format, hdr.Name, hdr.Size)
	}
}

如果业务还要消费正文，应在当前循环中读取 tr，再调用下一次 Next。不要把 Header 保存下来后误以为它包含文件内容；Reader 是顺序流，Next 会丢弃当前条目尚未读完的数据并推进到下一项。

失败处理：重新写入时创建新的 Header

官方文档特别提醒：从 Reader.Next 取得 Header、修改后再交给 Writer.WriteHeader 时，为了向前兼容，应创建一个新的 Header，只复制确实要保留的字段。不要把来源不明的 Header 整体浅拷贝后原样转写，因为未知或未来扩展字段可能带入不符合输出目标的语义。

下面示例针对普通文件、目录和符号链接，明确输出为 PAX。PAX 适合需要 UTF-8 长文件名、扩展记录或亚秒时间的场景；若下游只接受 USTAR 或 GNU，应按真实兼容目标替换 Format，并处理对应限制。

func newPAXHeader(src *tar.Header) *tar.Header {
	pax := make(map[string]string, len(src.PAXRecords))
	for key, value := range src.PAXRecords {
		pax[key] = value // 中文注释：复制业务明确要保留的扩展记录
	}

	return &tar.Header{
		Typeflag:   src.Typeflag,
		Name:       src.Name,
		Linkname:   src.Linkname,
		Size:       src.Size,
		Mode:       src.Mode,
		Uid:        src.Uid,
		Gid:        src.Gid,
		Uname:      src.Uname,
		Gname:      src.Gname,
		ModTime:    src.ModTime,
		AccessTime: src.AccessTime,
		ChangeTime: src.ChangeTime,
		PAXRecords: pax,
		Format:     tar.FormatPAX, // 中文注释：固定为下游确认支持的 PAX
	}
}

如果没有强制格式要求，可以不设置新 Header 的 Format。Writer.WriteHeader 会按 USTAR、PAX、GNU 的顺序选择第一个能编码这些字段的格式。反过来，显式指定 FormatUSTAR 后又写入非 ASCII 长文件名、过大数值或不受支持的时间字段，Writer 应返回错误，而不是静默生成另一个格式。

记录与复盘：把来源兼容问题留在边界层

线上处理第三方 tar 时，日志至少保留归档来源标识、条目名、Typeflag、Size、Format 和 Next 错误类型；不要记录文件正文或敏感路径。统计未知格式出现在哪个生产工具或供应方，再决定是继续宽松读取、在入口统一转成 PAX，还是要求上游修复头部。

最终判断可以压缩成两条：err 非空先处理错误，err 为空再解释 Format；读取到未知格式不等于输出时也要保留未知格式。需要重新打包时，用新 Header 表达你真正支持的字段和目标格式，兼容边界就会清楚很多。

相关问题

FormatUnknown 会导致文件内容读取失败吗？

不一定。只要本次 Next 返回 err == nil，Reader 已建立当前条目的读取边界，可以继续读取正文。是否接受该来源仍由业务兼容策略决定。

为什么不直接把 FormatUnknown 改成 FormatPAX？

格式标签不是修复开关。来源 Header 可能包含 PAX 不支持或业务不想保留的字段。更稳妥的方式是新建 Header、复制需要的字段，再让 Writer 检查目标格式是否能编码。

什么时候应该让 Writer 自动选择格式？

当输出消费者同时支持常见 tar 变体，并且你更关心“字段可被正确编码”而不是固定格式时，可以保留 Format 零值。若要与只支持某一格式的旧系统交换文件，应显式设置并处理其限制。