Go archive/tar 怎么导出带亚秒时间的 PAX 归档

要让 Go 导出的 tar 归档保留文件修改时间的亚秒部分，关键不是手工拼接时间字段，而是在每个 tar.Header 上明确设置 Format: tar.FormatPAX。如果格式留空，Writer.WriteHeader 会选择能容纳当前字段的格式；在未指定 PAX 的普通场景里，ModTime 的写入精度可能回到整秒。

一、先把时间精度问题定位到 Header.Format

tar 的 USTAR 头把修改时间按秒表达，PAX 则通过前置的扩展头保存更高精度的时间值。Go 文档对三种常见格式的能力区分很直接：USTAR 不支持亚秒时间，GNU 也不提供亚秒时间，而 PAX 支持。

因此，看到“写入前有纳秒，读回后只剩整秒”，先检查 Header 的 Format，不要先怀疑 time.Time 或时区。时区会影响显示方式，但不会替你把一个 PAX 时间字段变成 USTAR 秒值。

二、用 FormatPAX 写入带亚秒 ModTime 的归档

最小写法是给 Header 指定 FormatPAX，把精确的 time.Time 放到 ModTime，再按正常顺序写入文件内容。下面的示例用内存缓冲区，便于把写入和读取放在同一段验证代码里：

package main

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

func main() {
	var buf bytes.Buffer
	tw := tar.NewWriter(&buf)
	stamp := time.Date(2026, 11, 5, 8, 10, 12, 345678901, time.UTC)
	hdr := &tar.Header{
		Name:    "report.txt",
		Mode:    0600,
		Size:    int64(len("pax demo\n")),
		ModTime: stamp,
		Format:  tar.FormatPAX, // 明确要求 PAX，保留 ModTime 的亚秒部分
	}
	if err := tw.WriteHeader(hdr); err != nil {
		log.Fatal(err) // 头写入失败时停止，避免继续写入不完整归档
	}
	if _, err := io.WriteString(tw, "pax demo\n"); err != nil {
		log.Fatal(err) // 内容写入失败时不要把缓冲区当成完整归档
	}
	if err := tw.Close(); err != nil {
		log.Fatal(err) // Close 会写入归档结束标记，必须检查错误
	}
	fmt.Println("archive bytes:", buf.Len())
}

这里没有手工写 PAXRecords 里的时间键。由 Header.ModTime 和 FormatPAX 共同决定时间表达更稳妥，也避免把扩展键名、数值格式和字段优先级写错。若同时设置自定义 PAX 记录，仍应把它们限制在自己的大写命名空间中。

三、读取归档并核对纳秒部分

验证时不要把时间先格式化成 2006-01-02 15:04:05，那样会主动丢掉小数部分。重新创建 Reader，调用 Next 取出条目后，直接比较 UnixNano：

tr := tar.NewReader(bytes.NewReader(buf.Bytes()))
readHeader, err := tr.Next()
if err != nil {
	log.Fatal(err) // Next 失败时不能把零值时间当成读取结果
}
fmt.Println(readHeader.Name, readHeader.ModTime.UTC().Format(time.RFC3339Nano))
if readHeader.ModTime.UnixNano() != stamp.UnixNano() {
	log.Fatal("ModTime precision was lost") // 直接比较纳秒，避免格式化造成误判
}
fmt.Println("sub-second ModTime preserved")

Reader.Next 返回的 Header 是读取结果的边界；后续若要继续读文件内容，再从当前 Reader 读取 Header.Size 对应的数据。这个例子只核对时间，因此不需要把内容读完后再判断时间。

四、兼容性边界与常见误区

• 只设置 ModTime 不等于保留亚秒。 时间值有纳秒并不代表 tar 头一定能表达它，格式选择仍是关键。
• 不要用字符串秒值回填。 例如先调用 Unix() 再构造时间，会在写入前就截断精度。
• 不要为了时间精度改选 GNU。 Go 文档把 PAX 作为提供亚秒时间的格式；GNU 的优势是另一组扩展能力。
• 目标工具要实际支持 PAX。 如果下游只接受 USTAR，必须在兼容性和时间精度之间做取舍，不能靠 Header 字段绕过格式限制。

相关问题

为什么读回的时间看起来还是整秒？

先确认展示代码没有使用只到秒的格式，再确认写入 Header 的确是 tar.FormatPAX。最后用 UnixNano 比较，而不是肉眼看日志。

可以直接手工设置 PAX 的 mtime 键吗？

一般不需要。优先设置 Header.ModTime 和 FormatPAX，让标准库生成记录；手工设置只适合你明确掌握 PAX 键语义并需要额外扩展字段的场景。