Go archive/tar Header.Format 怎样选择 USTAR、PAX 和 GNU

如果你只是要写一个普通、短路径的 tar 归档，让 Header.Format 保持零值通常就够了；archive/tar 会在 Writer.WriteHeader 时选择能够完整编码当前 Header 的格式。如果归档包含长文件名、长链接名、扩展属性，或者下游系统要求格式稳定，就应该明确考虑 tar.PAX，而不是只看文件后缀。

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

核心判断是：先看 Header 中的字段能否被目标格式完整表达，再决定显式指定 USTAR、PAX、GNU，还是交给 Writer 自动选择。格式不是装饰字段，它会影响长路径、扩展字段和跨工具读取。

先区分 Header.Format 的两种用法

tar.Header 里的 Format 是归档头格式的选择项。你可以显式写入 tar.USTAR、tar.PAX 或 tar.GNU；也可以保留零值，让 Writer 根据 Header 当前字段选择一个能够编码它的格式。

package main

import (
    "archive/tar"
    "bytes"
)

func buildHeader(explicit bool) (*bytes.Buffer, error) {
    var archive bytes.Buffer
    writer := tar.NewWriter(&archive)

    header := &tar.Header{
        Name: "docs/readme.txt",
        Mode: 0600,
        Size: int64(len("hello\n")),
    }
    if explicit {
        // 需要稳定的扩展字段能力时，显式选择 PAX。
        header.Format = tar.PAX
    }

    // Writer 会先检查 Header 是否能被选定格式完整编码。
    if err := writer.WriteHeader(header); err != nil {
        return nil, err
    }
    // 写入长度必须与 Header.Size 一致，避免下一个 Header 写入时出错。
    if _, err := writer.Write([]byte("hello\n")); err != nil {
        return nil, err
    }
    // Close 会写出归档尾部填充，必须保留它的错误。
    if err := writer.Close(); err != nil {
        return nil, err
    }
    return &archive, nil
}

显式格式适合需要固定归档契约的场景；零值自动选择适合由库决定最小可用格式的场景。无论哪种方式，WriteHeader 仍可能因为字段无法编码、当前文件内容未写完或 Writer 已处于错误状态而返回错误。

USTAR、PAX 和 GNU 到底差在哪里

三种格式的差异，重点不在“哪个更高级”，而在 Header 的字段范围和下游工具支持。USTAR 使用固定长度字段；PAX 通过扩展记录表达更长的名称、链接名和额外元数据；GNU 也提供超出传统 USTAR 限制的扩展，但它更偏向 GNU tar 生态。

这里有一个容易忽略的边界：Header.Format 的能力描述不等于所有解包工具的兼容性保证。一个格式能够编码某字段，只说明 Go 的 tar Writer 有对应表达方式；真正交付时，还要把接收方能否识别 PAX 或 GNU 写入工程约定。

Writer.WriteHeader 如何决定格式

当 Header.Format 已明确设置，Writer 会按这个格式编码 Header；当它是零值，Writer 会从可用格式中寻找能够表达当前字段的方案。可以把这件事理解为“Header 字段约束 -> Format 选择 -> 写入归档头”，而不是把 Format 当成事后标签。

func writeEntry(writer *tar.Writer, name string, body []byte, format tar.Format) error {
    header := &tar.Header{
        Name: name,
        Mode: 0600,
        Size: int64(len(body)),
        Format: format,
    }

    // format 为 tar.Format(0) 时，交给 Writer 选择能完整编码 Header 的格式。
    if err := writer.WriteHeader(header); err != nil {
        return err
    }
    // body 的长度来自同一份数据，避免 Size 与实际写入量不一致。
    _, err := writer.Write(body)
    return err
}

如果你把 format 固定为 tar.USTAR，却传入超过 USTAR 字段边界的名称，错误应该被当作输入与格式契约不匹配来处理，而不是简单改短名称。若格式选择由 Writer 自动完成，则应记录最终归档格式或在读取侧用 Header.Format 辅助诊断。

需要稳定兼容时为什么常选 PAX

在备份、构建产物和跨机器迁移中，文件路径长度和附加元数据往往不是作者能长期控制的。PAX 通过扩展记录保留这些信息，通常比强行把名称截短更可靠，也比依赖 GNU 私有扩展更容易作为跨工具契约讨论。

func writePAXEntry(writer *tar.Writer, path string, body []byte) error {
    header := &tar.Header{
        Name: path,
        Mode: 0644,
        Size: int64(len(body)),
        Format: tar.PAX,
    }

    // 显式 PAX 表达长路径或扩展元数据，避免依赖自动选择结果。
    if err := writer.WriteHeader(header); err != nil {
        return err
    }
    // 当前文件没有写完前不能开始下一个 Header。
    if _, err := writer.Write(body); err != nil {
        return err
    }
    return nil
}

显式 PAX 不是“所有场景都更好”。如果接收端只实现了非常老的 USTAR 读取器，PAX 反而会带来兼容问题；这时应在接口契约中限制路径与元数据，而不是让发布端静默截断。

读取侧的 Format 可以怎样用

读取归档时，Reader.Next 会返回每个条目的 Header，Header.Format 是对该条目格式的最佳努力判断。它适合写日志、做兼容性提示和定位“为什么某条目出现扩展记录”，但不应被当作对整个归档所有条目的绝对证明。

func inspectFormats(reader *tar.Reader) error {
    for {
        header, err := reader.Next()
        if err == io.EOF {
            // 没有更多条目时，正常结束读取。
            return nil
        }
        if err != nil {
            // 保留格式解析错误，交给调用方决定是否中止。
            return err
        }
        // 记录条目名与最佳努力识别出的格式，便于兼容性排查。
        log.Printf("%s: %s", header.Name, header.Format)
    }
}

上面示例需要补充 io 和 log 导入；它只展示读取逻辑，不代表已经在本机执行。对于迁移工具，建议同时记录归档生成端的显式 Format、读取端是否接受扩展记录，以及遇到 FormatUnknown 时的处理策略。

最后用一张清单做格式选择

• 字段都在传统固定长度内、接收方强调旧式兼容：考虑 USTAR。
• 存在长路径、长链接名、扩展属性或更大数值：优先评估 PAX。
• 下游明确是 GNU tar 生态，并且接受 GNU 扩展：再考虑 GNU。
• 不需要固定格式时可用零值，让 Writer 选择可编码格式，但仍要处理 WriteHeader 错误。
• 开始下一个 Header 前，必须确保前一个条目的 Size 对应内容已经写完。

常见问题

Header.Format 为零值是不是一定使用 USTAR？

不是。零值表示不预先锁定格式，Writer 会根据当前 Header 的字段寻找能够编码的格式，具体结果取决于字段内容。

长文件名应该直接改短吗？

如果路径是业务身份的一部分，不建议静默改短；先选择能表达长名称的格式，并确认接收端支持该格式。

PAX 和 GNU 可以只按文件扩展名区分吗？

不可以。tar 文件扩展名不能可靠说明头格式，应该依据生成端的 Format 契约和读取端对扩展记录的支持判断。

为什么 WriteHeader 会在写下一个条目时才暴露问题？

Writer 需要维护当前条目的剩余数据和填充边界；如果前一个条目没有写满，切换到下一个 Header 时就可能返回错误。要把每次写入的错误都保留下来。