Go archive/tar 处理 PAX 长路径

我在归档构建产物时最容易踩到的坑，不是 tar.Writer 不会写文件，而是目录层级一深，文件名就超过传统 USTAR 的能力范围。Go 的正确处理方式是把格式明确设为 tar.FormatPAX：PAX 会在原条目前面写入扩展头，保存完整的长名称，读取端再由 archive/tar 透明还原到 Header.Name。

官方地址：https://pkg.go.dev/archive/tar

只要接收方支持 POSIX PAX，长路径归档优先使用 FormatPAX；不要把路径截短后硬塞进 USTAR，也不要因为 GNU 能容纳长名称就默认选择 GNU。格式选择本质上取决于“路径能力”和“对端兼容性”两项约束。

长路径为什么会把 USTAR 推到边界

archive/tar 把 USTAR、PAX 和 GNU 视为不同格式。官方文档给出的能力差异很直接：USTAR 的名称字段有限，而 PAX 可以用扩展头保存无限长度的名称；GNU 也支持长名称，但它不是 POSIX PAX 的同一套扩展。

因此，问题不应该简单写成“文件名太长就换一个字符串字段”。真正需要比较的是：归档包要交给谁读取、对方是否按 POSIX PAX 解析，以及长路径之外是否还需要高精度时间等扩展字段。对多数跨平台 Go 服务，PAX 是更容易解释的默认选择。

写入长路径时显式使用 FormatPAX

写入时可以直接给 tar.Writer 一个缓冲区，再把 Header.Format 设为 FormatPAX。WriteHeader 会根据这个设置写入需要的扩展头；业务代码仍然只需要维护完整的 Header.Name 和文件内容。

package main

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

func buildPAXTar() ([]byte, error) {
	var buf bytes.Buffer
	tw := tar.NewWriter(&buf)
	name := "release/2026/服务/配置/很长的构建产物名称/config.production.yaml"
	header := &tar.Header{
		Name: name,
		Mode: 0o644,
		Size: int64(len("port: 8080\n")),
		Format: tar.FormatPAX, // 明确要求用 PAX 承载长名称。
	}
	if err := tw.WriteHeader(header); err != nil {
		return nil, fmt.Errorf("写入 tar 头失败: %w", err)
	}
	if _, err := io.WriteString(tw, "port: 8080\n"); err != nil {
		return nil, fmt.Errorf("写入条目内容失败: %w", err)
	}
	// 先关闭 Writer，让末尾块和内部状态完整写入缓冲区。
	if err := tw.Close(); err != nil {
		return nil, fmt.Errorf("关闭 tar Writer 失败: %w", err)
	}
	return buf.Bytes(), nil
}

这里的长路径保留在 Header.Name 中，没有手动拆分，也没有添加 GNU 专用字段。Size 必须与后续写入的字节数一致；如果实际内容来自文件，应该使用文件大小或边读边写的明确方案，不能让头部大小与正文脱节。

这个示例的图示重点是“完整名称进入 Header，PAX 负责承载扩展，Writer 负责输出归档字节”，它是静态说明，不代表某个本机运行结果。

读取时让 Reader 还原完整的 Name

读取 PAX 包时不需要自己解析扩展头。Reader.Next 会跳过 PAX 的元数据条目，并返回对应文件的 *tar.Header；如果正文不需要保存，就必须把当前条目的内容消费完，再调用下一次 Next。

package archive

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

func listNames(r io.Reader) error {
	tr := tar.NewReader(r)
	for {
		h, err := tr.Next()
		if err == io.EOF {
			return nil // 没有更多条目，读取正常结束。
		}
		if err != nil {
			return fmt.Errorf("读取 tar 条目失败: %w", err)
		}
		fmt.Printf("name=%s format=%s size=%d\n", h.Name, h.Format, h.Size)
		// 先消费当前条目，下一次 Next 才会定位到下一个条目。
		if _, err := io.Copy(io.Discard, tr); err != nil {
			return fmt.Errorf("跳过 %q 的内容失败: %w", h.Name, err)
		}
	}
}

读取端关心的是恢复后的 Header.Name 和 Header.Format，而不是扩展头的内部布局。若只想列目录，使用 io.Copy(io.Discard, tr) 消费内容；若要解压，则把同一个 tr 复制到目标文件，并根据名称做路径安全策略。

PAX、USTAR 和 GNU 怎么选

我实际做选择时会先问接收方，而不是先问“哪个格式能写进去”。如果对端明确支持 POSIX PAX，长路径、非 ASCII 名称和扩展时间字段都更适合交给 PAX；如果必须兼容一个只接受 USTAR 的老系统，就只能限制名称与字段范围，不能指望设置一个常量绕过接收方限制。

Header.Format 不写时，Writer 会选择能够编码当前 Header 的格式；这对普通短路径很方便，但在跨系统交换场景里，我更倾向于显式写出 FormatPAX，让包的意图清楚可读。长路径也不等于可以忽略目标系统的解包安全策略。

几个容易忽略的边界

• 不要截短 Name。截短会造成同名覆盖或丢失目录层级，PAX 的意义就是保存原始名称。
• 不要漏掉 Close。tar.Writer.Close 负责写出归档尾部；文件类 Writer 还要单独关闭底层文件。
• 不要把 Format 当成强制读取结果。Reader 会尽力判断格式，文档也说明不合规包可能得到 FormatUnknown。
• 不要把长路径问题扩大成压缩问题。archive/tar 负责 tar 容器，gzip、zstd 等压缩层应由外部 Reader/Writer 组合处理。

相关问题

Go 的 tar.Writer 会自动选择 PAX 吗？

当 Header.Format 未指定时，Writer 会按 USTAR、PAX、GNU 的能力顺序选择可编码当前 Header 的格式。需要稳定的跨系统格式时，直接设置 tar.FormatPAX 更清楚。

读取 PAX 时需要手动读取 TypeXHeader 吗？

通常不需要。archive/tar 会透明处理 PAX 的扩展头，调用方通过 Next 得到文件条目和完整名称即可。