Go archive/tar 怎么写入自定义 PAX 扩展字段

给 Go 生成的 tar 增加构建版本、来源仓库或归档批次时，直接在 tar.Header.PAXRecords 中写入自定义键，并把 Header.Format 明确设为 tar.FormatPAX。键名使用大写厂商命名空间，例如 GOLANG.pkg.version，值保持非空 UTF-8；不要手工拼接 PAX 文本，也不要把扩展字段塞进文件内容。

先分清 PAX 扩展头和 tar 文件正文

tar 本质上是按顺序排列的文件条目。PAX 格式会在原始条目前增加扩展头，扩展头里的键值只服务于后面的条目。Go 的 archive/tar 已经负责编码这层结构，因此业务代码只需要维护 Header.PAXRecords。

自定义记录建议使用大写命名空间。下面的 GOLANG.pkg.version 表示包版本，GOLANG.build.source 表示生成来源，二者都属于归档元数据而不是文件正文。

用 Header.PAXRecords 写入自定义字段

下面的示例把一个内存中的配置文件写入归档。关键点是先计算正文的字节长度，再一次性写入头和正文；PAXRecords 的内容由 archive/tar 负责落盘。

package main

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

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

    body := []byte("mode = production\n") // 正文只放配置内容，元数据单独写入 PAX
    hdr := &tar.Header{
        Name:   "config/app.conf",
        Mode:   0o600,
        Size:   int64(len(body)), // Size 必须是当前文件正文的字节数
        Format: tar.FormatPAX,
        PAXRecords: map[string]string{
            "GOLANG.pkg.version": "2026.09",
            "GOLANG.build.source": "release-pipeline",
        }, // 自定义键使用稳定的厂商命名空间
    }

    if err := tw.WriteHeader(hdr); err != nil {
        log.Fatal(err) // 头写入失败时不要继续写正文
    }
    if _, err := tw.Write(body); err != nil {
        log.Fatal(err) // 正文长度超过 Size 会得到写入错误
    }
    if err := tw.Close(); err != nil {
        log.Fatal(err) // Close 负责补齐块并写入归档结束标记
    }

    fmt.Printf("archive bytes: %d\n", archive.Len()) // 这里只展示归档总长度
}

Size 是最容易写错的边界：它只对应 config/app.conf 的正文长度，不包含 PAX 扩展头、tar 块填充和结束标记。写入正文少于这个长度时，下一次 WriteHeader 或 Close 会发现当前条目未完成；多写则会返回 ErrWriteTooLong。

读取时从 Header 取回 PAXRecords

读取端不要把 PAX 扩展头当作一个需要业务代码跳过的文件。tar.Reader.Next 会推进到真实条目，并将解析出的扩展字段放在返回的 Header.PAXRecords 中；正文仍通过 Reader.Read 读取。

func readEntry(archiveBytes []byte) error {
    tr := tar.NewReader(bytes.NewReader(archiveBytes))
hdr, err := tr.Next()
if err != nil {
    return err // Next 的错误先处理，不能直接解引用 hdr
}

version := hdr.PAXRecords["GOLANG.pkg.version"] // 业务字段从 Header 读取
if version == "" {
    return fmt.Errorf("missing package version") // 缺失时按兼容策略决定拒绝或降级
}

buf := new(bytes.Buffer)
if _, err := io.Copy(buf, tr); err != nil {
    return err // 当前条目的正文仍来自 Reader
}
    return nil // 调用方随后可以按需解析 buf 中的文件正文
}

生产代码还应区分“字段不存在”和“字段值为空”。规范建议自定义键和值都非空，因此空值通常应作为生成端或上游工具不合规来处理，而不是静默当成默认版本。

写入和兼容性中的几个边界

另外，Xattrs 是历史字段，官方文档建议改用 PAXRecords；若同时设置二者，写头时 Xattrs 对对应扩展属性有优先级。不要把同一业务字段同时放入多个命名空间。

常见问题

PAXRecords 的键可以随便写吗？

不建议。使用大写厂商名加点号再接字段名，例如 GOLANG.pkg.version，并确保键和值都是非空 UTF-8，避免和其他工具的扩展字段撞名。

为什么写完 PAXRecords 还要设置 FormatPAX？

显式设置能表达归档协议意图，尤其适合需要亚秒级时间或自定义扩展的场景；不设置时库会按能容纳当前 Header 的格式选择，但调用方对输出格式的控制更弱。

读取不到自定义字段怎么办？

先确认写入端调用了 WriteHeader 且最终调用 Close，再确认读取端检查的是 Next 返回的同一个条目。若归档由外部工具生成，还要确认它没有丢弃未知 PAX 键。

把业务元数据放在 PAXRecords、把正文长度留给 Header.Size，再用 Close 完成归档，是 Go 写自定义 PAX 字段时最稳妥的分层方式。