Go archive/tar.Writer 怎样保留文件模式和修改时间

用 Go 生成 tar 包时，如果只把文件内容写进去，解包后常见的结果是权限模式不符合预期，或者修改时间只剩下秒级精度。问题通常不在 Writer.Write，而在写入前创建的 tar.Header 没有带上正确的文件元数据。

最稳妥的做法是先用 tar.FileInfoHeader 从 fs.FileInfo 生成基础 Header，再根据归档内路径改写 Header.Name。普通场景直接保留 Mode 和 ModTime 就够了；如果确实需要更细的时间信息，则显式选择 tar.FormatPAX，不要把格式选择交给默认值。

文件模式来自 Header.Mode，修改时间来自 Header.ModTime；写入前补齐这两个字段，并让 Header.Size 与实际写入字节数一致，解包时才有稳定的元数据基础。

先区分文件信息和 tar Header

os.FileInfo 或更通用的 fs.FileInfo 描述的是当前文件系统对象，包含名称、大小、权限模式、目录判断和修改时间等信息。tar.Header 则是归档格式中的一条记录，两者字段相似，但不是同一个对象。

tar.FileInfoHeader 会从 fs.FileInfo 创建一个部分填充的 Header。它使用 FileInfo.Name() 作为基础名称，所以打包子目录时，通常还要手动把 Header.Name 改成归档内的相对路径。目录的名称需要带结尾斜杠，这也是标准库在处理目录 Header 时采用的约定。

func newHeader(info fs.FileInfo, archiveName string) (*tar.Header, error) {
	// FileInfoHeader 负责把权限模式、类型和修改时间映射到 Header。
	hdr, err := tar.FileInfoHeader(info, "")
	if err != nil {
		return nil, fmt.Errorf("创建 tar 头失败: %w", err)
	}
	// FileInfo.Name 只有基础名，归档路径要由调用方明确指定。
	hdr.Name = archiveName
	return hdr, nil
}

这个函数没有直接写文件，是因为元数据转换和归档写入最好分开。调用方可以在这里统一处理路径规范化、是否允许符号链接以及格式选择，避免把本地绝对路径意外写入归档。

用 FileInfoHeader 保留模式和修改时间

对普通文件而言，FileInfoHeader 已经会把文件的权限模式和修改时间带入 Header。写入时要遵循固定关系：先调用 WriteHeader，再向同一个 tar.Writer 写入不超过 Header.Size 的内容。模式和时间属于 Header 元数据，不需要混在文件正文里。

如果手工构造 Header，也要明确设置 Mode、ModTime、Size 和 Name。手工方式适合归档内容不是来自本地文件的场景，但更容易漏字段；只要输入已经有 fs.FileInfo，优先使用标准库转换。

func addFile(tw *tar.Writer, sourcePath, archiveName string) error {
	file, err := os.Open(sourcePath)
	if err != nil {
		return fmt.Errorf("打开源文件失败: %w", err)
	}
	defer file.Close() // 文件句柄由本函数负责关闭。

	info, err := file.Stat()
	if err != nil {
		return fmt.Errorf("读取文件信息失败: %w", err)
	}
	hdr, err := tar.FileInfoHeader(info, "")
	if err != nil {
		return fmt.Errorf("生成 Header 失败: %w", err)
	}
	hdr.Name = archiveName // 使用归档内路径，不写入本机绝对路径。

	if err := tw.WriteHeader(hdr); err != nil {
		return fmt.Errorf("写入 tar Header 失败: %w", err)
	}
	if _, err := io.Copy(tw, file); err != nil {
		return fmt.Errorf("写入文件内容失败: %w", err)
	}
	return nil
}

这里的关键不是把 info.Mode() 和 info.ModTime() 再手动抄一遍，而是让 FileInfoHeader 完成一次受控映射。hdr.Name 仍然要由业务决定，因为归档名称和源文件在磁盘上的名称可能不同。

需要细粒度时间时选择 PAX

默认情况下，Writer.WriteHeader 会选择能够编码当前 Header 的格式。如果 Header.Format 没有显式指定，标准库会把 ModTime 按秒取整，并忽略 AccessTime 与 ChangeTime，这样可以避免普通归档因为时间字段而被迫使用更大的扩展头。

如果业务只关心常见的修改时间，默认行为通常足够。如果需要保留亚秒级的 ModTime，或者确实要表达访问时间、变化时间等扩展字段，就应该把 hdr.Format 设为 tar.FormatPAX，并在文档中说明接收方需要支持 PAX。

func preserveExtendedTime(hdr *tar.Header, keepSubsecond bool) {
	if keepSubsecond {
		// 显式选择 PAX，避免默认格式把 ModTime 取整到秒。
		hdr.Format = tar.FormatPAX
		return
	}
	// 不需要扩展时间时保留默认格式，兼容性和体积更可控。
	hdr.Format = tar.FormatUnknown
}

FormatPAX 是格式能力的选择，不是“时间一定恢复成功”的保证。目标解包工具、目标文件系统以及权限模型都可能限制最终恢复结果。文章里要把“写入 Header 的信息”和“解包后落盘的效果”分开描述。

完成一个可复用的打包函数

下面把前面的规则组合起来：打开文件、取得元数据、生成 Header、决定归档路径、写入内容，最后关闭 Writer。Close 不能省略，因为它负责刷新当前条目的填充并写入 tar 尾部；如果正文长度不足，Close 也会把问题暴露出来。

func CreateTar(dst io.Writer, sourcePath, archiveName string, keepSubsecond bool) error {
	tw := tar.NewWriter(dst)
	defer func() {
		// 真正的 Close 错误在显式调用处返回，这里的 defer 只兜底释放引用。
	}()

	if err := addFileWithFormat(tw, sourcePath, archiveName, keepSubsecond); err != nil {
		return err
	}
	if err := tw.Close(); err != nil {
		return fmt.Errorf("关闭 tar Writer 失败: %w", err)
	}
	return nil
}

func addFileWithFormat(tw *tar.Writer, sourcePath, archiveName string, keepSubsecond bool) error {
	file, err := os.Open(sourcePath)
	if err != nil {
		return fmt.Errorf("打开源文件失败: %w", err)
	}
	defer file.Close() // 复制完成后关闭源文件。

	info, err := file.Stat()
	if err != nil {
		return fmt.Errorf("获取源文件信息失败: %w", err)
	}
	hdr, err := tar.FileInfoHeader(info, "")
	if err != nil {
		return fmt.Errorf("创建 Header 失败: %w", err)
	}
	hdr.Name = archiveName // 归档名由调用方控制，避免暴露本机路径。
	if keepSubsecond {
		hdr.Format = tar.FormatPAX // 需要亚秒级时间时选择扩展格式。
	}
	if err := tw.WriteHeader(hdr); err != nil {
		return fmt.Errorf("写入 Header 失败: %w", err)
	}
	if _, err := io.Copy(tw, file); err != nil {
		return fmt.Errorf("复制文件内容失败: %w", err)
	}
	return nil
}

示例把 Close 的错误显式返回，而不是在 defer 中静默忽略。实际项目还应检查 archiveName 是否为相对路径、是否包含不允许的路径段，以及是否要接受符号链接；元数据保留和路径安全是两件事。

检查解包后的元数据边界

写入端成功只说明 tar 流中的 Header 和正文已经按格式编码，不能直接推出目标系统会完全恢复所有属性。可以用下面的速查表确定预期：

特别是 Mode 不等于“解包后一定按这个权限落盘”，ModTime 也不等于“接收端一定保存同样精度”。写文章或设计接口时，把归档格式承诺、解包工具能力和本地文件系统能力分别写清楚，排查会更快。

最后记住这几个判断

• 已有 fs.FileInfo 时，优先用 tar.FileInfoHeader，再改写归档内的 Header.Name。
• Header.Mode 决定写入的权限和模式位，Header.ModTime 决定写入的修改时间信息。
• 默认格式适合普通秒级时间；需要亚秒级或其他扩展时间时，显式使用 tar.FormatPAX。
• Header.Size、正文写入量和 Writer.Close 必须放在同一条错误处理链中。
• 归档元数据保留不替代路径、链接、权限和目标文件系统的安全策略。

相关问题

为什么 FileInfoHeader 后还要修改 Header.Name？因为 fs.FileInfo.Name() 通常只有基础文件名，归档内路径需要由打包逻辑明确指定。

不设置 FormatPAX 会丢失 ModTime 吗？不一定会丢失，但未显式指定格式时会按秒取整；是否需要 PAX 取决于时间精度要求。

Header.Mode 能保证解包后权限完全一致吗？不能。解包工具、目标系统和进程权限都可能影响最终落盘结果。

为什么一定要检查 Writer.Close？它会刷新当前条目的填充并写入归档尾部，未写足 Header.Size 或底层输出失败都可能在这里体现。