Go archive/tar 流式写入文件元数据

我在做备份导出时，最初把文件先读进 []byte，小文件看不出问题，一遇到几百 MB 的日志归档，内存就跟着文件大小一起涨。Go 的 archive/tar 更适合另一种写法：先写入描述条目的 Header，再把打开的文件流复制给 tar.Writer。关键是 Header 的 Size 必须和实际写入量一致，归档路径也要在写头前补齐。

流式写入 tar 的固定顺序是“获取元数据 → 补齐归档名称 → WriteHeader → 复制内容 → Close”。目录和符号链接只写描述信息；普通文件才复制数据，并且必须检查复制错误与字节数。

先把 FileInfo 变成可用的 Header

tar.FileInfoHeader 只返回部分填充的头信息。由于 fs.FileInfo.Name() 通常只是文件基名，归档需要层级路径时要手动覆盖 Header.Name。下面的辅助函数只负责准备元数据，写入动作留给后面的统一循环。

// headerForEntry 把文件系统元数据映射成归档内的条目描述。
func headerForEntry(pathInArchive string, info fs.FileInfo, linkTarget string) (*tar.Header, error) {
	hdr, err := tar.FileInfoHeader(info, linkTarget)
	if err != nil {
		return nil, fmt.Errorf("build tar header for %q: %w", pathInArchive, err)
	}
	// FileInfoHeader 默认更接近基名，这里明确保存归档内的相对路径。
	hdr.Name = pathInArchive
	return hdr, nil
}

对目录，标准库会在名称后补斜杠；对符号链接，linkTarget 会进入链接目标字段。不要用 os.Stat 跟随链接，否则很容易把链接误判成目标文件。

WriteHeader 之后直接复制文件流

写入顺序不能颠倒：WriteHeader 会根据 Header.Size 准备当前条目，之后的 Write 才属于这个条目。使用 io.Copy 可以让数据分块流过输出端，不需要创建和文件等大的缓冲区。

// appendRegularFile 写入一个普通文件，并核对 Header.Size 与实际复制量。
func appendRegularFile(tw *tar.Writer, sourcePath string, hdr *tar.Header) error {
	src, err := os.Open(sourcePath)
	if err != nil {
		return fmt.Errorf("open %q: %w", sourcePath, err)
	}
	defer src.Close() // 文件句柄只服务于当前条目，复制结束就释放。

	if err := tw.WriteHeader(hdr); err != nil {
		return fmt.Errorf("write header %q: %w", hdr.Name, err)
	}
	n, err := io.Copy(tw, src)
	if err != nil {
		return fmt.Errorf("copy %q: %w", hdr.Name, err)
	}
	if n != hdr.Size {
		return fmt.Errorf("short tar entry %q: wrote %d, want %d", hdr.Name, n, hdr.Size)
	}
	return nil
}

如果源文件在 Stat 与读取之间变小，字节数检查能暴露不完整条目；如果它变大，tar.Writer.Write 会在超过 Header.Size 时返回错误。这里不把“复制函数返回 nil”当成完整性证明。

目录、符号链接与普通文件要分开

归档元数据不等于文件内容。目录只需要写一个目录类型的 Header；符号链接需要用 Lstat 读取链接本身，并把 Readlink 的目标交给 FileInfoHeader。只有普通文件才打开并复制内容。

// writeEntry 按文件类型选择“只写头”或“写头并复制内容”。
func writeEntry(tw *tar.Writer, archiveName, diskPath string) error {
	info, err := os.Lstat(diskPath) // Lstat 不跟随符号链接，保留链接类型。
	if err != nil {
		return fmt.Errorf("lstat %q: %w", diskPath, err)
	}
	linkTarget := ""
	if info.Mode()&os.ModeSymlink != 0 {
		linkTarget, err = os.Readlink(diskPath)
		if err != nil {
			return fmt.Errorf("readlink %q: %w", diskPath, err)
		}
	}
	hdr, err := headerForEntry(archiveName, info, linkTarget)
	if err != nil {
		return err
	}
	if info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
		if err := tw.WriteHeader(hdr); err != nil {
			return fmt.Errorf("write metadata %q: %w", hdr.Name, err)
		}
		return nil
	}
	return appendRegularFile(tw, diskPath, hdr)
}

这个边界也避免了一个常见错误：给目录设置一个看似合理的文件大小并复制目录路径，结果既没有目录内容，也破坏了条目语义。目录的遍历是另一层职责，当前函数只写一个条目。

最后用 Close 判断归档是否收口

多个条目连续写入时，下一次 WriteHeader 会要求上一个普通文件已经写满；全部条目结束后还要调用 tw.Close()，让 Writer 写出归档结束所需的尾部块，并把底层写入错误带回调用方。一个清晰的外层收尾可以这样组织：

// buildTar 把条目按顺序写入 out，并保留最后一个关闭错误。
func buildTar(out io.Writer, entries []struct{ Name, Path string }) error {
	tw := tar.NewWriter(out)
	for _, entry := range entries {
		if err := writeEntry(tw, entry.Name, entry.Path); err != nil {
			return err
		}
	}
	// Close 负责写结束块，也可能暴露底层输出的错误。
	if err := tw.Close(); err != nil {
		return fmt.Errorf("close tar writer: %w", err)
	}
	return nil
}

生产代码通常还会把输出端换成文件、HTTP 响应或对象存储上传流；这些目的地不改变条目顺序规则。若需要保存自定义元数据，优先在 WriteHeader 前明确设置 PAX 记录，并为归档名称约定稳定的相对路径。

几个容易漏掉的边界

这套写法的核心不是某个“大缓冲区”参数，而是把元数据和内容流分开：Header 先确定条目边界，io.Copy 负责传输，Close 负责收口。只要目录、链接和普通文件沿着各自的语义处理，archive/tar 就能稳定地用于大文件导出。

相关问题

Header.Name 为什么要自己修改？

因为 FileInfo 的 Name 通常只有基名；归档需要目录层级时，必须在写 Header 前设置目标相对路径。

文件大小变化时应该继续发布归档吗？

不建议静默接受。把大小不一致作为错误返回，或者在业务层先生成稳定快照，再进行流式归档。