Go archive/tar.Writer.WriteHeader 怎样写入目录条目

用 Go 的 archive/tar.Writer.WriteHeader 写目录时，核心不是给目录准备一段正文，而是提交一个类型为 tar.TypeDir 的 Header。通常把 Name 写成以斜杠结尾的路径，并保持 Size 为 0；Header 成功后直接切换到下一个条目，不要对目录调用 Write。

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

先区分目录 Header 与普通文件 Header

WriteHeader 只是把当前条目的描述写入归档，并准备接收该条目的数据。目录和普通文件共用 tar.Header，但它们的类型和后续动作不同。

手动构造 Header 时，尾部斜杠是最直观的目录路径表达。若从 fs.FileInfo 转换，官方 tar.FileInfoHeader 会在识别到目录时给名称追加斜杠；如果是自己填写 Header，就不要把这个细节交给调用方猜。

用 WriteHeader 写入目录条目

下面的例子把目录和一个文件写入同一个内存归档。目录 Header 提交后没有正文写入，新的文件 Header 会把 Writer 的当前条目切换到普通文件。

package main

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

func main() {
	var buf bytes.Buffer
	tw := tar.NewWriter(&buf)

	// 目录只有元数据，不准备可写正文；Name 用斜杠表达目录路径。
	dir := &tar.Header{Name: "assets/", Mode: 0755, Typeflag: tar.TypeDir}
	if err := tw.WriteHeader(dir); err != nil {
		panic(err) // Header 失败时不要继续写入后续条目。
	}

	body := []byte("hello tar\n")
	file := &tar.Header{Name: "assets/readme.txt", Mode: 0644, Size: int64(len(body))}
	if err := tw.WriteHeader(file); err != nil {
		panic(err) // 新 Header 会切换到普通文件条目。
	}
	if _, err := tw.Write(body); err != nil {
		panic(err) // 写入量必须不超过 file.Size。
	}
	if err := tw.Close(); err != nil {
		panic(err) // Close 负责补齐归档尾部并报告未写完的条目。
	}
	fmt.Println("tar bytes:", buf.Len())
}

这里的关键顺序是“目录 Header → 文件 Header → 文件数据 → Close”。不需要手动调用 Flush；下一次 WriteHeader 或 Close 会处理当前条目的必要填充。

在目录条目后继续写入普通文件

tar 是按条目排列的流。目录本身不会像文件夹一样替你创建父子关系，归档中真正的层级来自每个条目的 Name。因此要把文件放进目录，只需让文件名带上同一目录前缀，并重新提交文件 Header。

普通文件的 Size 应按字节计算，不能用字符数替代。写入少于 Size 时，后续 Header 或 Close 会暴露当前条目未完成；写入超过 Size 则会得到 ErrWriteTooLong。目录即使把 Size 写成非零，也不能把它当作正文容器。

处理 WriteHeader 与 Close 的边界

• 目录写入 ErrWriteTooLong：检查 Typeflag 是否为 tar.TypeDir，并删除目录后的 Write。
• 下一个 Header 报当前文件未完成：核对上一个普通文件是否已经写满 Header.Size，不要只看 Write 没有返回错误。
• 归档结尾异常：保留 Close 的错误处理，它不仅是释放对象，也会完成归档收尾。

相关问题

目录名称一定要以斜杠结尾吗？

手动构造目录 Header 时建议保留斜杠，路径语义更清晰；从 FileInfoHeader 转换目录时，标准库会自动追加。

目录条目的 Size 可以写成 0 以外的值吗？

目录属于无数据体的特殊类型，实践中应保持为 0，并把文件内容写到独立的普通文件条目中。

必须为每个文件先写目录条目吗？

不一定。归档层级主要由文件条目的 Name 表达；是否额外写目录条目取决于你是否需要保留目录元数据。