Go archive/tar 如何连续写入多个归档条目

要把多个文件连续写进一个 tar 归档，关键是只创建一个 tar.Writer，然后对每个文件重复“WriteHeader 描述条目、Write 写入内容”的组合。每次进入下一个条目前，前一个条目的字节数必须达到 Header.Size；所有条目结束后再调用 Close，让归档补上结束块。

多个条目为什么要共用一个 Writer

archive/tar 的 Writer 是顺序写入器。它内部只维护一个“当前条目”，调用 WriteHeader 后，后续的 Write 都属于这个 Header 描述的文件。因此不要为每个文件新建一个 Writer；那样得到的是多段互不相连的 tar 数据，而不是一个包含多个成员的归档。

先写 Header，再写够 Size 指定的内容

下面的示例把两个文件写入内存缓冲区。这里用 len(data) 计算精确大小，并在每次写入后检查返回值；真实项目把 bytes.Buffer 换成文件或网络输出流即可。

package main

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

type entry struct {
    name string
    data []byte
}

func buildTar(entries []entry) ([]byte, error) {
    var buf bytes.Buffer
    tw := tar.NewWriter(&buf)

    for _, item := range entries {
        hdr := &tar.Header{
            Name:    item.name,
            Mode:    0600,
            Size:    int64(len(item.data)), // Size 必须等于当前条目的真实字节数。
            ModTime: time.Unix(0, 0).UTC(), // 固定时间便于构建结果可重复。
        }
        if err := tw.WriteHeader(hdr); err != nil {
            return nil, fmt.Errorf("write header %q: %w", item.name, err)
        }
        if _, err := tw.Write(item.data); err != nil {
            return nil, fmt.Errorf("write data %q: %w", item.name, err)
        }
    }
    if err := tw.Close(); err != nil {
        return nil, fmt.Errorf("close tar: %w", err) // Close 可能暴露底层输出流错误。
    }
    return buf.Bytes(), nil
}

第二次调用 WriteHeader 时，标准库会先处理前一个条目的补齐；如果前一个条目只写了部分内容，新的 Header 会返回错误。反过来，如果实际写入的数据超过 Size，也不应该依赖 Writer 帮你“自动扩容”，应先修正大小契约。

流式内容要把短读和长读分开处理

文件较大时不必先读成 []byte。先取得稳定的文件大小写入 Header，再用 io.CopyN 把恰好 Size 个字节送入当前条目。它返回 EOF，通常说明源文件比声明的大小短；如果源文件变大，复制到 Size 后还应额外检查文件是否发生了变化。

func addFile(tw *tar.Writer, name string, size int64, src io.Reader) error {
    hdr := &tar.Header{Name: name, Mode: 0600, Size: size}
    if err := tw.WriteHeader(hdr); err != nil {
        return fmt.Errorf("header %q: %w", name, err)
    }
    if _, err := io.CopyN(tw, src, size); err != nil {
        return fmt.Errorf("content %q: %w", name, err) // 短读必须阻止进入下一个条目。
    }
    return nil
}

这个函数没有关闭 src，因为资源所有权仍属于调用方；但最外层的归档流程必须负责 tw.Close()。把“谁创建、谁关闭”写清楚，能避免文件描述符和网络响应流被错误地重复关闭。

关闭后用 Reader.Next 核对条目

生成函数成功只代表写入流程没有返回错误，接收方仍可能关心成员顺序、名称和大小。用一个新的 Reader 从归档字节中逐个取 Header，可以快速检查结构；读完当前条目后再调用 Next，不要把所有成员内容混在一起解析。

func inspectTar(data []byte) error {
    tr := tar.NewReader(bytes.NewReader(data))
    for {
        hdr, err := tr.Next()
        if err == io.EOF {
            return nil // 正常结束，不是一个损坏条目。
        }
        if err != nil {
            return fmt.Errorf("read tar header: %w", err)
        }
        fmt.Printf("%s %d bytes\\n", hdr.Name, hdr.Size)
        if _, err := io.Copy(io.Discard, tr); err != nil {
            return fmt.Errorf("read %q: %w", hdr.Name, err) // 消费当前内容后再取下一个 Header。
        }
    }
}

相关问题

WriteHeader 后可以直接写下一个 Header 吗？

不可以。当前条目必须先写满 Header.Size；否则下一个 WriteHeader 会因为当前文件未完成而返回错误。

为什么 tar.Writer 一定要 Close？

Close 会完成当前条目的收尾并写入归档结束块。只把缓冲区字节取出来而不关闭 Writer，接收方可能无法把它当作完整归档处理。

可以并发写入同一个 tar.Writer 吗？

不建议。Writer 按单一当前条目维护状态；并发调用会打乱 Header 与内容的对应关系。需要并发读取源文件时，可以并发准备数据，但最终写入 tar 的部分应保持单线程顺序。