Go问答：archive/tar PAX长文件名在归档后为什么被截断怎样完成一个可复用的最小示例

如果 Go 生成的 tar 归档里长文件名看起来被截断，先不要把问题归咎于 UTF-8。archive/tar 的关键在于归档格式：USTAR 把名称放在固定大小的字段中，而 PAX 使用扩展记录保存更长的路径。写入时显式设置 Header.Format = tar.FormatPAX，读取时通过 Reader.Next 获取合并后的 Header.Name，通常就能保留完整路径。

Go 的 PAX 写法不是把文件名手工拆到多个字段，而是让 archive/tar 写出 PAX 扩展头；不要手动读取原始块并把 USTAR 的固定字段当成最终文件名。

长文件名为什么会和 USTAR 冲突

tar 归档的格式并不只有一种。Go 官方文档列出了 USTAR、PAX 和 GNU 等格式，其中 USTAR 的名称字段有固定上限，PAX 则允许名称使用扩展记录表达。路径包含较多目录层级、中文字符，或只是长度超过旧格式承载范围时，如果仍强制使用 USTAR，就可能得到写入错误、降级后的路径，或者被下游工具显示成不完整名称。

Go 的 Header 同时保存逻辑名称和格式选择。没有指定格式时，Writer.WriteHeader 会选择能够承载当前字段的格式；为了让归档协议更明确、减少调用方和解包器之间的猜测，批量导出或跨系统交换时可以直接指定 tar.FormatPAX。PAX 的扩展头对普通 Reader 是透明的，业务代码不需要先解析一个“隐藏文件”再拼接名称。

写入时把 PAX 格式和长路径放在 Header 里

最小示例可以使用 bytes.Buffer 代替磁盘文件，先把归档字节放在内存中。示例特意构造较长的 UTF-8 路径，并在 Header 中同时设置 Name、Size、Mode 和 Format。这里的 Size 是文件内容的字节数，不是文件名长度。

package main

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

func buildPAXArchive() ([]byte, error) {
    var archive bytes.Buffer
    tw := tar.NewWriter(&archive)

    // 使用较长的 UTF-8 路径，验证名称不会受 USTAR 固定字段影响。
    name := "资料/2026/项目归档/客户交付/非常详细的构建产物说明文件.txt"
    body := []byte("PAX keeps the complete path.")
    hdr := &tar.Header{
        Name:   name,
        Mode:   0600,
        Size:   int64(len(body)),
        Format: tar.FormatPAX,
    }
    // WriteHeader 写入文件头，并准备接收 Size 指定数量的内容。
    if err := tw.WriteHeader(hdr); err != nil {
        return nil, fmt.Errorf("写入 tar 头: %w", err)
    }
    // Write 的总字节数不能超过 Header.Size，否则会返回 ErrWriteTooLong。
    if _, err := tw.Write(body); err != nil {
        return nil, fmt.Errorf("写入文件内容: %w", err)
    }
    // Close 负责补齐当前块并写入归档尾部，不能省略。
    if err := tw.Close(); err != nil {
        return nil, fmt.Errorf("关闭 tar writer: %w", err)
    }
    return archive.Bytes(), nil
}

func main() {
    data, err := buildPAXArchive()
    if err != nil {
        log.Fatal(err)
    }

    tr := tar.NewReader(bytes.NewReader(data))
    hdr, err := tr.Next()
    if err != nil && err != io.EOF {
        log.Fatal(err)
    }
    // Reader.Next 会处理 PAX 扩展记录，Name 应保持完整路径。
    fmt.Println(hdr.Name)
}

这个示例的关键不是把 FormatPAX 写进 PAXRecords，而是告诉 Writer 采用 PAX 头格式。PAXRecords 更适合放置自定义扩展键值；普通长文件名由 Header.Name 表达即可。

读取时为什么要相信 Reader.Next 返回的 Header.Name

PAX 会在实际文件头前增加类型为 TypeXHeader 的扩展记录，用键值记录表达超出传统字段的属性。archive/tar.Reader.Next 会读取并合并这些记录，然后返回当前归档项的 *tar.Header。因此，应用层应该读取返回头部的 Name，再把当前文件内容交给 io.Copy 或其他流式处理函数。

func readFirstEntry(data []byte) (string, error) {
    tr := tar.NewReader(bytes.NewReader(data))
    hdr, err := tr.Next()
    if err != nil {
        return "", fmt.Errorf("读取归档项: %w", err)
    }
    // 先使用完整名称；当前条目的正文从 tr 继续读取。
    if _, err := io.Copy(io.Discard, tr); err != nil {
        return "", fmt.Errorf("跳过文件内容: %w", err)
    }
    return hdr.Name, nil
}

不需要为了“找到 PAX 文件”而把底层流倒回去，也不应该把 TypeXHeader 当成业务文件展示给用户。对于连续读取，下一次调用 Next 会自动丢弃当前文件尚未读取的剩余内容，然后移动到下一个归档项。

仍然看到截断时，按这几个边界排查

如果 Go 内部读取出的 hdr.Name 已经完整，而最终目录中的名称仍然变短，问题通常不在 archive/tar 的 Reader，而在归档链路的其他一段。

另外，长文件名不等于任意路径都应该写入归档。跨平台归档时仍应避免绝对路径和带有 .. 的不安全路径；名称保留下来，只说明编码格式能够承载它，不代表解包端应该无条件把它写入目标目录。

一段速查：什么时候显式使用 PAX

• 路径可能超过 USTAR 的固定名称长度，或包含非 ASCII 字符时，优先使用 tar.FormatPAX。
• 写入完成必须检查 Writer.Close，因为归档尾部和当前块的补齐在这里完成。
• 读取名称使用 Reader.Next 返回的 Header.Name，不要直接截取原始 tar 块。
• 如果 Go 读回完整但外部解包截断，优先排查下游工具的 PAX 支持，而不是重写文件名。

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

相关问题

FormatPAX 还需要手动设置 PAXRecords 吗？

保存长文件名不需要。把完整路径放进 Header.Name 并选择 FormatPAX 即可；只有要携带自定义扩展属性时，才考虑使用命名空间形式的 PAX 记录。

为什么示例必须调用 Writer.Close？

Close 会补齐当前文件的数据块并写入归档尾部。缺少它时，内存中的字节可能不是完整 tar，读取端自然无法稳定得到预期名称。

长路径完整保存后就一定能被所有系统解包吗？

不一定。PAX 能表达更长的名称，但最终还取决于目标解包器和目标文件系统的限制。跨系统交付时，应把目标工具的兼容性作为独立检查项。