Go archive/tar 出错时怎么排查长名称

用 Go 的 archive/tar 打包深层目录时，如果 WriteHeader 报 archive/tar: cannot encode header、header field too long 或类似的名称过长错误，先不要截断文件名。最常见的原因是把长路径强制写成了 USTAR；把格式交给库自动选择，或明确设置为 tar.FormatPAX，才能保留完整名称。

先看错误发生在写入还是读取

生成归档时，失败点通常是 tw.WriteHeader(h)。此时长名称还没有成为归档条目，应该检查 h.Name、h.Linkname、h.Uname 和 h.Gname，因为不只是文件名会触发头部字段限制。尤其要留意代码是否把 Format 固定为 tar.FormatUSTAR。

读取已有归档时，失败点多在 tr.Next()。Go 的读取器会处理 PAX 扩展头和 GNU 长名称记录，正常情况下返回的 Header.Name 应该是完整路径。若返回 ErrInsecurePath，那是路径包含非本地形式的安全问题，不等于名称太长，不能通过切短字符串混过去。

固定 USTAR 时，长路径为什么会被拒绝

tar 头部格式不是同一个容量模型。Go 官方格式说明列出了 USTAR、PAX、GNU 的差异：USTAR 的 Name 是有限字节字段，PAX 和 GNU 可以承载更长的名称。中文路径还要按 UTF-8 字节数理解，不能只数字符个数。

下面的例子故意固定 USTAR，用来复现问题；注释说明了判断点，示例并不要求在本机执行。

package main

import (
	"archive/tar"
	"bytes"
	"fmt"
	"strings"
)

func main() {
	var buf bytes.Buffer
	tw := tar.NewWriter(&buf)

	// 通过重复目录制造较长路径，故意测试固定 USTAR 的容量边界。
	longName := strings.Repeat("reports/", 40) + "result.json"
	h := &tar.Header{
		Name:   longName,
		Mode:   0o644,
		Size:   int64(len("ok")),
		Format: tar.FormatUSTAR, // 固定格式便于观察名称字段不足的错误。
	}
	if err := tw.WriteHeader(h); err != nil {
		// 这里优先记录原始错误，不要先截断 Name 再重试。
		fmt.Println(err)
		return
	}
	_, _ = tw.Write([]byte("ok")) // 写入内容后再由 Close 补齐归档尾部。
}

这个错误说明“当前头部无法按指定格式编码”，并不说明文件系统不允许该路径。若业务必须兼容只接受 USTAR 的旧工具，就要在业务层设计较短的归档名，并另存原始路径映射；如果目标是保留路径，优先切换支持扩展字段的格式。

让格式自动选择，或明确使用 PAX

通常最小修复是删除 Format: tar.FormatUSTAR。文档说明，当 Header.Format 未指定时，Writer.WriteHeader 会按 USTAR、PAX、GNU 的顺序选择能够编码该头部的格式；长名称会自然落到 PAX 或 GNU。

func writeLongEntry(tw *tar.Writer, name string, data []byte) error {
	h := &tar.Header{
		Name:   name,
		Mode:   0o644,
		Size:   int64(len(data)),
		Format: tar.FormatPAX, // 显式保留长名称及 UTF-8 路径。
	}
	if err := tw.WriteHeader(h); err != nil {
		return fmt.Errorf("写入 tar 头部失败: %w", err) // 保留原始错误，方便定位字段。
	}
	if _, err := tw.Write(data); err != nil {
		return fmt.Errorf("写入条目内容失败: %w", err) // 内容长度由 Writer 按 Size 约束。
	}
	return nil
}

选择 PAX 后仍要保证 Size 与实际写入字节数相符，并在所有条目写完后调用 tw.Close()。不要把 PAX 当作无限制容器：空字节、无效字段、错误的条目类型或写入长度不一致，仍然会产生独立错误。

读取时确认名称完整，并单独处理安全路径

读取排错不要只打印“读取成功”。把 Header.Name、Header.Format 和条目类型放在一起记录，才能判断上游归档究竟使用了 PAX、GNU 还是未知格式。

func listEntries(r io.Reader) error {
	tr := tar.NewReader(r)
	for {
		h, err := tr.Next()
		if errors.Is(err, io.EOF) {
			return nil // 到达归档尾部，说明所有条目都已遍历。
		}
		if err != nil {
			if errors.Is(err, tar.ErrInsecurePath) {
				return fmt.Errorf("归档路径不安全: %w", err) // 与长名称错误分开处理。
			}
			return fmt.Errorf("读取 tar 条目失败: %w", err)
		}
		fmt.Printf("name=%q format=%s type=%q\\n", h.Name, h.Format, h.Typeflag)
	}
}

如果只需要提取到本地目录，还应在写文件前根据自身策略检查名称是否为本地相对路径，并拒绝 ../、绝对路径或不允许的链接目标。长度排错解决的是编码容量，安全检查解决的是解包边界，两者应保留为两个判断分支。

常见问题

只把长名称截断，能不能快速发布？

不建议。截断可能造成同名覆盖，也会丢失目录语义。只有在兼容 USTAR 的硬约束下，才应明确设计短名并保存原名映射。

读取端需要自己解析 PAX 的 path 吗？

一般不需要。archive/tar.Reader 会透明处理标准的 PAX 长名称记录，业务侧直接使用返回的 Header.Name，并记录格式用于排查即可。

为什么改了 Name 仍然报 header field too long？

长字段可能是 Linkname、用户名或组名，也可能仍然残留了 FormatUSTAR。按字段逐一检查，并保留原始错误文本，通常比继续缩短路径更快定位。