Go archive/tar Header.Xattrs 怎样写入文件扩展属性

如果要把文件扩展属性写进 Go 的 tar 归档，关键不是把属性放进普通的 Header 字段，而是让它进入 PAX 扩展记录。Header.Xattrs 会把每个键值表达成 SCHILY.xattr. 命名空间下的记录；写入时应明确使用 tar.FormatPAX，并保证键名不含等号、值使用有效的 UTF-8 字符串。

官方文档：https://pkg.go.dev/archive/tar@go1.27.3#Header

最小可靠做法是：给 Header 设置 Format: tar.FormatPAX，填充 Xattrs，先调用 WriteHeader 再写正文，最后关闭 tar.Writer。如果还需要表达自定义 PAX 字段，优先直接使用 PAXRecords。

这里的“扩展属性”是归档条目中的元数据，不等于 Go 自动从当前操作系统读取了文件的 xattr。采集动作仍需要业务代码或平台工具完成，本文只讨论怎样把已经得到的键值放进 tar。

Xattrs 实际会落到哪一层

Xattrs 是一个 map[string]string，例如 user.comment 到 由归档任务写入。Go 的 tar 实现会把它放入 PAX 的 SCHILY.xattr. 命名空间，所以最终可以理解为：

Header.Xattrs["user.comment"]
→ PAXRecords["SCHILY.xattr.user.comment"]
→ tar 归档条目的扩展头记录

这种映射有两个实用含义。第一，Xattrs 不是一个可以被 USTAR 或 GNU 格式原生承载的独立字段，它依赖 PAX 表达。第二，属性键应该只表达属性名称本身，不要把 SCHILY.xattr. 前缀重复写进键名；前缀由 tar 写入层负责拼接。

用 FormatPAX 写入一条带扩展属性的条目

下面的示例把一段配置文本写成 tar 条目，并附带两个示意属性。代码没有从磁盘读取真实 xattr，属性值由调用方提供；这样更容易把归档表达和平台采集职责分开。

package main

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

func buildArchive() ([]byte, error) {
    var buf bytes.Buffer
    tw := tar.NewWriter(&buf)
    data := []byte("mode=production\n")

    header := &tar.Header{
        Name:     "config/app.env",
        Mode:     0o640,
        Size:     int64(len(data)),
        Format:   tar.FormatPAX, // 扩展属性依赖 PAX，显式指定格式更稳妥。
        Xattrs: map[string]string{
            "user.comment": "由归档任务写入", // 键名只写属性名，不重复 SCHILY.xattr. 前缀。
            "user.owner":   "release-job",
        },
    }

    if err := tw.WriteHeader(header); err != nil {
        return nil, fmt.Errorf("写入 tar 头失败: %w", err)
    }
    if _, err := tw.Write(data); err != nil {
        return nil, fmt.Errorf("写入 tar 正文失败: %w", err)
    }
    if err := tw.Close(); err != nil {
        return nil, fmt.Errorf("关闭 tar 写入器失败: %w", err)
    }
    return buf.Bytes(), nil
}

要点只有三处：Size 必须与真正写入的字节数一致；WriteHeader 必须先于正文；Close 不能省略，因为写入器需要补齐归档尾部。示例中的 FormatPAX 不是装饰字段，它直接表达了该条目需要 PAX 能力。

为什么必须使用 PAX 格式

当 Header.Xattrs 非空时，Go 的格式选择会把条目限制在 PAX 能力范围内。若把 Format 固定成 tar.FormatGNU，就会形成不兼容的组合；不要期待 GNU 头替你保存这组扩展属性。

如果让格式保持零值，Writer 会尝试选择能够编码当前 Header 的格式；但在需要长期兼容、跨语言读取或写入属性的任务中，显式指定 tar.FormatPAX 更容易审查，也能避免以后新增字段后格式选择发生变化。

Xattrs 与 PAXRecords 同时存在时谁优先

旧代码常把两种写法混在同一个 Header 里：

header.Xattrs = map[string]string{
    "user.comment": "来自 Xattrs",
}
header.PAXRecords = map[string]string{
    "SCHILY.xattr.user.comment": "来自 PAXRecords",
}

它们指向同一个 PAX 键时，Xattrs 的内容在 WriteHeader 时优先。也就是说，上面的同名属性不能靠后写入的 map 来“覆盖”出确定结果。迁移旧代码时，建议统一使用 PAXRecords 表达新字段：

header := &tar.Header{
    Name:   "config/app.env",
    Format: tar.FormatPAX,
    PAXRecords: map[string]string{
        "SCHILY.xattr.user.comment": "明确写入 PAX 命名空间",
        "GOLANG.pkg.version":         "v1",
    },
}

自定义 PAX 键使用大写厂商或项目命名空间，关键词不要包含 =，键和值保持非空 UTF-8。Xattrs 适合兼容已有调用方；新代码若需要表达不止一类扩展记录，直接维护 PAXRecords 会更清晰。

四个容易把问题带偏的边界

• 属性为空：nil 或空 map 不会产生扩展属性记录，条目仍可使用普通格式。
• 键名非法：包含等号、非 UTF-8 字节或不符合命名空间约定时，不要把错误归因给 tar 解包器；先修正输入键。
• 格式冲突：非空 Xattrs 与 FormatGNU 不是“降级写入”，而是能力不匹配，应改为 PAX。
• 职责混淆：Header.Xattrs 只描述归档头中的属性，不负责读取 Linux、macOS 或其他系统的文件扩展属性。

可以把这篇文章压缩成一句判断：需要归档扩展属性时，选择 PAX；属性键只写自己的命名部分；同名字段不要同时维护；写完正文后关闭 writer。这样既能保留元数据，也能让后续读取代码知道这些属性属于 PAX 扩展层。

相关问题

Header.Xattrs 会自动读取文件系统属性吗？

不会。它只是待写入的 map。文件系统属性的采集需要调用方自己完成，再把结果转换成字符串键值。

为什么设置 Xattrs 后还要显式写 FormatPAX？

因为 Xattrs 的归档表达依赖 PAX。显式指定可以把格式要求写在代码里，避免后续维护者误改为 GNU 或把格式选择误认为普通字段兼容。