Go archive/tar怎样流式写入大归档文件为什么结果为空或不符合预期

我第一次把一批大文件写成 tar 归档时，最先遇到的不是内存暴涨，而是归档“看起来创建成功”，解开后却没有正文，或者最后一个文件只剩一半。问题通常不在“流式”三个字，而在 archive/tar 的协议顺序：每个文件都要先写一个包含 Size 的头，再写恰好对应长度的内容，最后还要让 Close 完成填充和归档尾部。

官方地址：https://pkg.go.dev/archive/tar

要稳定写入大归档，先拿到每个条目的准确字节数，再按 WriteHeader → Write → Close 的顺序推进。文件过大时用 io.Copy 逐块搬运；输入长度未知时先落盘或预先计算，不要用一个猜测的 Size 直接开写。

• 不进内存：把磁盘文件或网络流直接交给 io.Copy，不要先 ReadFile。
• 不写空头：tar.Header.Size 是后续正文长度的边界，不是可选备注。
• 不吞错误：WriteHeader、io.Copy 和 Close 都要检查返回值。

先看懂 archive/tar 的一条写入链

archive/tar 把 tar 视为一串文件条目，每个条目先有 Header，再跟着该条目的数据。tar.NewWriter 只负责把这个序列写到下层 io.Writer，下层可以是普通文件、网络连接或其他流式目标，所以它本身不会因为文件很大就自动把全部内容缓存到内存。

我觉得最容易误解的一点是：流式写入并不等于“可以不告诉 tar 文件有多大”。Header 在正文之前，Size 必须先写进头部；Writer 才知道当前条目应该接受多少字节，并在下一条 Header 或最终 Close 时补齐块边界。

从磁盘文件逐块写入大归档

对普通文件来说，最稳妥的做法是先通过 Stat 取得准确大小，再把文件句柄交给 io.Copy。io.Copy 会循环搬运数据，不要求把整个文件放进一个大字节切片里。

package main

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

// addFile 把一个磁盘文件作为单独条目流式写入 tar。
func addFile(tw *tar.Writer, path string) error {
	f, err := os.Open(path)
	if err != nil {
		return fmt.Errorf("打开源文件: %w", err)
	}
	defer f.Close() // 源文件只在当前条目写完后关闭。

	info, err := f.Stat()
	if err != nil {
		return fmt.Errorf("读取文件信息: %w", err)
	}

	hdr := &tar.Header{
		Name:    filepath.Base(path),
		Mode:    0o600,
		Size:    info.Size(),
		ModTime: info.ModTime().Truncate(time.Second),
		Format:  tar.FormatPAX, // 长文件名或大文件优先使用 PAX 表达。
	}
	if err := tw.WriteHeader(hdr); err != nil {
		return fmt.Errorf("写入 tar 头: %w", err)
	}

	if _, err := io.Copy(tw, f); err != nil {
		return fmt.Errorf("写入 tar 正文: %w", err)
	}
	return nil
}

func main() {
	out, err := os.Create("bundle.tar")
	if err != nil {
		panic(err)
	}
	defer out.Close() // 关闭底层文件，错误由上层流程负责记录。

	tw := tar.NewWriter(out)
	for _, path := range []string{"large-a.log", "large-b.log"} {
		// 每个条目独立检查，避免一个失败被后续条目掩盖。
		if err := addFile(tw, path); err != nil {
			panic(err)
		}
	}
	// Close 会写入最后的填充和归档尾部，不能只关闭底层文件。
	if err := tw.Close(); err != nil {
		panic(fmt.Errorf("关闭 tar: %w", err))
	}
}

这里的关键不是 FormatPAX 一定要手动指定，而是把格式选择和数据长度写清楚。官方文档说明，未指定格式时 Writer 会选择能够表达当前 Header 的格式；显式使用 PAX 则适合需要更长名称、UTF-8 或更细时间精度的场景。真正影响“正文为空”的，仍然是 Header 是否成功写入、后续是否把数据复制给了同一个 Writer。

输入长度未知时，为什么不能直接猜 Size

如果数据来自 HTTP 请求体、消息队列或另一个实时管道，调用 WriteHeader 时可能还不知道最终字节数。tar 的普通条目没有“先写正文，最后回头修改 Size”的通用写法，因为 Header 已经位于正文前面。

我的取舍通常是先把输入写入临时文件，拿到 Stat().Size() 后再进入 tar；如果源协议本身提供可信的 Content-Length，也可以把它作为候选长度，但仍应处理实际读取长度与声明不一致的错误。临时落盘会增加一次磁盘写入，却换来了可收尾、可重试和可审计的归档条目。

// spoolAndAdd 先把未知长度的输入落到临时文件，再写入 tar。
func spoolAndAdd(tw *tar.Writer, name string, src io.Reader) error {
	tmp, err := os.CreateTemp("", "tar-spool-*")
	if err != nil {
		return fmt.Errorf("创建临时文件: %w", err)
	}
	tmpName := tmp.Name()
	defer os.Remove(tmpName) // 归档条目完成后清理中间文件。

	if _, err := io.Copy(tmp, src); err != nil {
		tmp.Close()
		return fmt.Errorf("缓存未知长度输入: %w", err)
	}
	if err := tmp.Close(); err != nil {
		return fmt.Errorf("关闭临时文件: %w", err)
	}

	// 重新打开后由 addFile 读取准确 Size，并以块方式复制到 tar。
	return addFileAs(tw, tmpName, name)
}

func addFileAs(tw *tar.Writer, path, archiveName string) error {
	f, err := os.Open(path)
	if err != nil {
		return err
	}
	defer f.Close() // 只关闭临时输入，不关闭 tar.Writer。
	info, err := f.Stat()
	if err != nil {
		return err
	}
	if err := tw.WriteHeader(&tar.Header{
		Name: archiveName,
		Mode: 0o600,
		Size: info.Size(),
	}); err != nil {
		return err
	}
	_, err = io.Copy(tw, f)
	return err
}

如果业务强制要求边读边传、又不允许临时存储，就要重新评估 tar 是否是合适的线格式：可以把归档拆成已知大小的分片，或者在上游协议中先传元数据再传正文。不要把 Size 填成零再继续写，Writer 会把这视为一个零长度条目。

结果为空或不符合预期时按四个证据排查

遇到“文件存在但解压没有内容”时，我会先看调用返回值，而不是先怀疑解压工具。以下四个证据基本能把问题缩到写入链路：

1. Header.Size 是否等于实际正文：写多了会遇到 ErrWriteTooLong；写少了，后续 Header 或 Close 可能报当前文件未完整写完。
2. 是否真的调用了 WriteHeader：只调用 tw.Write(data) 不会凭空创建一个可识别的文件条目，写入顺序必须从 Header 开始。
3. 是否检查了 WriteHeader、Write 或 io.Copy：如果底层磁盘或网络 Writer 提前失败，忽略返回值会让上层只看到一个不完整文件。
4. 是否检查了 tw.Close：关闭底层 os.File 不等于关闭 tar.Writer。Close 负责补齐当前条目并写归档尾部，失败也必须让任务失败。

官方接口对这些边界有明确约束：WriteHeader 会开始一个新文件，Header.Size 决定当前文件最多能写多少字节；Write 超过该大小会返回 ErrWriteTooLong；Close 会刷新填充并写入尾部。如果读归档，则用 Next 逐项推进，当前条目剩余数据会在进入下一项时被丢弃。

大文件场景下的几个实际取舍

这套写法对日志归档、备份打包和导出文件很合适，因为 tar 是顺序格式，写入端和读取端都可以沿着一个 io.Reader/io.Writer 走。但它只负责“打包”，不负责压缩；需要更小体积时，可以在 tar.Writer 外面包一层 gzip，例如先创建 gzip.NewWriter(out)，再把 gzip Writer 交给 tar.NewWriter，关闭顺序要从 tar 到 gzip 再到底层文件。

另一个边界是路径和安全。归档里的名称应来自业务允许的相对路径，并在解包端额外检查路径是否会逃出目标目录；写包时不能把用户输入的绝对路径、../ 路径原样当成信任信息。归档能正确生成，不代表解包策略已经安全。

我会把这套写法用在哪些地方

如果每个输入都是可 Stat 的普通文件，archive/tar 是简单而稳定的标准库方案；如果输入是未知长度的实时流，先落盘的成本值得换取格式完整性。对我来说，最重要的经验是把“文件大小”“写入顺序”“关闭结果”当作同一条事务看待：三者任何一个被忽略，归档就可能在表面成功的情况下留下空条目或截断内容。

常见问题

Header.Size 能不能先写成 0，最后再补内容？

不适合。Header 位于正文之前，Size 是 Writer 处理当前条目的边界。未知长度数据应先落盘或通过上游协议拿到准确长度。

为什么只关闭 os.File 还不够？

os.File 只代表底层输出，tar.Writer 还需要 Close 来补齐当前条目的块填充并写入归档尾部。两个 Close 的错误都应记录。

WriteHeader 后少写了一些字节会怎样？

当前条目没有完整结束，后续切换条目或调用 Close 时可能返回错误。不要忽略 io.Copy 的实际字节数和 Close 返回值。

archive/tar 会自动压缩文件吗？

不会。它只实现 tar 归档；需要压缩体积时，在外层组合 gzip 等压缩 Writer，并按正确的逆序关闭各层。