Go archive/tar怎样流式写入大归档文件怎样完成一个可复用的最小示例

用 Go 生成大 tar 文件时，关键不是把数据先拼成一个巨大的 []byte，而是让 tar.Writer 直接包住文件、网络或管道等 io.Writer。每个归档条目先写入一个包含准确 Size 的 tar.Header，然后用 io.Copy 把源数据分段送进去，内存占用就不会随着单个文件大小线性增长。

官方文档：https://pkg.go.dev/archive/tar

先明确 archive/tar 的写入模型

archive/tar 把 tar 看成一串顺序条目：一个条目由头部和内容组成，写完当前条目后才能开始下一个条目。tar.Header 描述名称、权限、修改时间和逻辑大小，tar.Writer 负责把这些字段和内容编码到目标写入器。

因此，流式写入的重点有两个：目标端只需要实现 io.Writer，源文件只需要实现 io.Reader；而当前条目的大小仍然要在写头部之前确定。图中的连线表达的是静态模块关系，不是某次程序运行的截图。

用一个可复用函数写入单个大文件

单文件场景可以把“打开源文件、读取大小、写入头部、复制内容、关闭归档”封装起来。下面的函数没有创建中间缓冲区，io.Copy 会通过内部缓冲持续搬运数据。

package main

import (
	"archive/tar"
	"io"
	"os"
	"path/filepath"
)

// packFile 把一个普通文件流式写成单文件 tar 归档。
func packFile(archivePath, sourcePath string) (err error) {
	source, err := os.Open(sourcePath)
	if err != nil {
		return err // 源文件打不开时，不创建一个看似成功的归档。
	}
	defer func() {
		if closeErr := source.Close(); err == nil {
			err = closeErr // 把源文件关闭错误保留下来。
		}
	}()

	info, err := source.Stat()
	if err != nil {
		return err // Header.Size 需要文件的逻辑字节数。
	}

	destination, err := os.Create(archivePath)
	if err != nil {
		return err
	}
	defer func() {
		if closeErr := destination.Close(); err == nil {
			err = closeErr // tar.Writer 关闭后再关闭底层文件。
		}
	}()

	tw := tar.NewWriter(destination)
	defer func() {
		if closeErr := tw.Close(); err == nil {
			err = closeErr // Close 会写入尾部并检查当前条目是否完整。
		}
	}()

	hdr := &tar.Header{
		Name:    filepath.Base(sourcePath),
		Mode:    int64(info.Mode().Perm()),
		Size:    info.Size(),
		ModTime: info.ModTime(),
		Format:  tar.FormatPAX, // PAX 对长文件名和 UTF-8 元数据更宽容。
	}
	if err = tw.WriteHeader(hdr); err != nil {
		return err
	}

	_, err = io.Copy(tw, source) // 内容直接流经 tar.Writer，不聚合到内存。
	return err
}

这个函数有一个容易忽略的前提：源文件在读取时应当保持稳定。如果文件可能被另一个进程持续追加，Stat 得到的大小和实际读到的字节数可能不一致；这时应先生成稳定快照，或由上游提供明确长度的输入流。

把大文件写入和内存占用分开

流式并不等于 tar 格式自动知道文件大小。写入每个条目前，仍要把 Header.Size 填好；流式只解决“内容如何到达 Writer”，不替你解决“条目边界在哪里”。因此，能从文件元数据获得长度时，直接使用 info.Size()；对网络流等未知长度输入，则需要由协议元数据、临时文件或其他上游约定提供长度。

如果调用方已经提供一个限定长度的 Reader，可以用 io.CopyN 明确边界，并检查复制结果：

func writeKnownSize(tw *tar.Writer, name string, src io.Reader, size int64) error {
	hdr := &tar.Header{
		Name: name,
		Mode: 0600,
		Size: size,
	}
	if err := tw.WriteHeader(hdr); err != nil {
		return err // 头部失败时不要继续写内容。
	}

	written, err := io.CopyN(tw, src, size) // 只把约定的 size 字节写入当前条目。
	if err != nil {
		return err // 源数据不足时通常会得到 io.ErrUnexpectedEOF。
	}
	if written != size {
		return io.ErrUnexpectedEOF // 额外保护，避免静默生成短条目。
	}
	return nil
}

Header.Size 过小，继续写入会触发 tar.ErrWriteTooLong；过大，当前条目没有写满，后续的 WriteHeader 或最终 Close 会报告错误。两种情况都不应该靠“发布后再解压试试”来兜底，而应在写入边界处保留原始错误。

多个文件按条目逐个写入

多文件归档的内存策略与单文件相同：打开一个源文件，写它的 Header，复制完后关闭源文件，再处理下一个条目。下面的辅助函数把每个文件的生命周期限制在一次调用里，避免同时持有大量文件描述符。

func addFile(tw *tar.Writer, sourcePath, archiveName string) error {
	source, err := os.Open(sourcePath)
	if err != nil {
		return err // 当前文件失败时，让上层决定是否终止整个归档。
	}
	defer source.Close() // 当前条目完成后立即释放文件描述符。

	info, err := source.Stat()
	if err != nil {
		return err
	}
	hdr := &tar.Header{
		Name: archiveName,
		Mode: int64(info.Mode().Perm()),
		Size: info.Size(),
	}
	if err := tw.WriteHeader(hdr); err != nil {
		return err
	}
	_, err = io.Copy(tw, source) // 仍然是 Reader 到 Writer 的分段复制。
	return err
}

// 使用示例：destination 必须在所有条目写完后再 Close。
func buildArchive(destination io.Writer, files []struct{ Path, Name string }) error {
	tw := tar.NewWriter(destination)
	for _, file := range files {
		if err := addFile(tw, file.Path, file.Name); err != nil {
			return err // 不跳过失败条目，避免得到内容不完整的归档。
		}
	}
	return tw.Close() // 写完全部条目后补齐归档尾部。
}

如果目标是 HTTP 响应或对象存储上传流，destination 可以直接换成对应的 io.Writer。但要注意，tar 条目通常需要先知道大小，不能因为输出目标支持流式上传，就省略 Header.Size。

格式、路径和压缩边界要单独处理

archive/tar 只负责 tar 容器，不负责 gzip、zstd 或其他压缩。需要 .tar.gz 时，应把 gzip.Writer 放在 tar Writer 外层：先由 tar 写入条目，再由 gzip 把 tar 字节压缩到最终目标。关闭时要先关 tar，再关 gzip，两个错误都要处理。

格式选择上，普通跨平台归档优先考虑 tar.FormatPAX；它能表达 UTF-8 文件名、较长字段和更细的时间信息。若目标系统明确要求传统 USTAR，再接受它对文件名、字段长度和大文件能力的限制。归档名称也应由调用方规范化，避免把本地绝对路径或不希望暴露的目录层级直接写入包内。

常见问题

为什么不能直接把大文件读进 bytes.Buffer 再写 tar？

可以做小文件示例，但大文件会让内存峰值随文件大小增长。使用 io.Copy 让源文件和 tar.Writer 之间保持流式传输，缓冲区只承担固定大小的搬运工作。

Header.Size 可以先填 0，写入时再增长吗？

不能。它决定当前条目的数据边界；除非输入协议允许回写头部，否则应在 WriteHeader 前取得准确长度。

为什么一定要调用 tar.Writer.Close？

Close 会处理当前条目的补齐和归档尾部。如果只关闭底层文件而没有关闭 tar.Writer，输出可能缺少必要的结束结构，后续读取会失败或暴露为不完整归档。

archive/tar 能直接生成 tar.gz 吗？

不能。它只生成 tar 字节流；压缩需要额外包一层 gzip 或其他压缩 Writer，并按正确的关闭顺序收尾。

把握住“先写准确 Header，再把 Reader 复制到 Writer”这条边界，就能把单文件、多文件和网络输出统一成同一套实现：数据持续流动，内存不再承担整个归档的暂存区。