Go tar 怎样写稀疏文件条目

Go 的 archive/tar 可以读取稀疏归档，并把空洞暴露为 Header.SparseHoles；但它的标准 Writer 目前不能直接把这个 sparse map 编码成 GNU 或 PAX 稀疏条目。也就是说，给 Header.SparseHoles 赋值并不会自动得到一个节省存储的 tar 文件。

如果目标只是生成兼容性最好的普通 tar，按逻辑大小写入完整数据即可，空洞会以零字节出现在归档流中。如果目标是保留真正的稀疏编码，就需要把 GNU/PAX 稀疏格式交给专门的归档器或自定义编码层。

稀疏文件到底要表达什么

稀疏文件有一个逻辑大小，但磁盘上只保存有内容的区间。例如逻辑文件大小是 1 GiB，前 4 KiB 有数据，中间几百 MiB 是空洞，末尾又有一段数据。空洞不是另一个文件，而是逻辑地址空间里“读取时应得到 NUL”的区间。

在 Go 的数据结构里，空洞由一组 SparseEntry 描述，每项使用 Offset 和 Length 表示区间。它们应当按偏移量升序排列、互不重叠，并且不能超过 Header.Size。下面的关系图只用于理解字段含义：

这里有一个容易混淆的点：SparseHoles 描述的是空洞，不是要写入 tar 的数据块。真正的稀疏编码还需要把这些区间转换为 GNU 或 PAX 规定的元数据和数据区顺序，这一步正是标准 Writer 尚未替调用方完成的工作。

先记住 archive/tar 的读写边界

官方包文档把 USTAR、PAX 和 GNU 的能力区分得很清楚：USTAR 不支持稀疏文件，PAX 可以通过扩展记录表达稀疏信息，GNU 格式原生支持稀疏文件。可是 archive/tar 的 Reader 与 Writer 能力并不对称：

• Reader.Next 能识别稀疏归档，并把空洞填入返回的 Header.SparseHoles。
• 对稀疏条目调用 Reader.Read 时，空洞位置按 NUL 字节读回。
• Writer 当前不会根据 Header.SparseHoles 自动写出 GNU/PAX sparse map。
• 因此，FormatPAX 或 FormatGNU 只表示目标格式选择，不等于 Writer 已经支持稀疏条目编码。

普通 tar 写法：保留逻辑内容，不误标 sparse

当兼容性优先、归档体积不是主要约束时，最稳妥的做法是不要设置 SparseHoles，只用逻辑文件大小写入一个普通条目。源文件即使本身是稀疏文件，通过读取也会把空洞表现为零字节，归档得到的是完整逻辑内容。

package main

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

func addRegularFile(tw *tar.Writer, src *os.File, name string, size int64) error {
	// 普通条目不声明 SparseHoles，Header.Size 是归档中要写出的逻辑字节数。
	h := &tar.Header{
		Name: name,
		Mode: 0o600,
		Size: size,
		Format: tar.FormatPAX,
	}
	if err := tw.WriteHeader(h); err != nil {
		return err
	}

	// 稀疏源文件的空洞会按零字节读出，CopyN 保证不多写或少写。
	_, err := io.CopyN(tw, src, size)
	return err
}

func main() {
	// 示例只展示条目写入函数，真实程序还应检查文件打开与归档 Close 错误。
}

这个写法的关键不是“让 tar 变稀疏”，而是让声明与实际流完全一致：Header.Size 是逻辑大小，io.CopyN 写出的也是同样多的字节。这样任何只支持普通 PAX/USTAR 读取的工具都能按常规文件处理它。

读取稀疏条目时怎样保留兼容性

如果输入来自 GNU tar、支持稀疏扩展的 PAX 归档或其他工具，读取端应同时处理两种情况：没有空洞描述的普通文件，以及带 SparseHoles 的稀疏文件。不要只根据 TypeGNUSparse 判断，因为 PAX 稀疏扩展可以使用普通条目类型配合扩展记录表达。

func inspectTar(r io.Reader) error {
	tr := tar.NewReader(r)
	for {
		h, err := tr.Next()
		if err == io.EOF {
			return nil
		}
		if err != nil {
			return err
		}

		// SparseHoles 为空表示普通条目；非空时记录空洞区间供业务展示或恢复。
		if len(h.SparseHoles) > 0 {
			for _, hole := range h.SparseHoles {
				fmt.Printf("%s hole offset=%d length=%d\\n", h.Name, hole.Offset, hole.Length)
			}
		}

		// Reader 会把空洞按 NUL 返回；消费完当前条目后才能进入下一项。
		if _, err := io.Copy(io.Discard, tr); err != nil {
			return err
		}
	}
}

上面的片段还需要在导入区加入 fmt；这里特意把“列出空洞”和“消费正文”放在一起，避免调用 Next 前忘记读完当前条目。若业务要恢复成磁盘上的稀疏文件，可以在确认平台支持后根据空洞区间调用操作系统能力；不能把 tar 的读取行为误当成目标文件一定会在磁盘上保持稀疏。

确实要生成 sparse map，应该怎样选方案

需求不同，落地方式也不同：

不要为了“看起来像稀疏文件”直接写出 TypeGNUSparse，也不要只把 Header.Format 改成 FormatGNU。没有匹配的 sparse map 元数据和数据区布局，接收端可能把它当成损坏条目，或者得到错误的逻辑内容。

常见误区

• 误区一：以为 SparseHoles 是 Writer 的开关。它是 Header 中的稀疏描述，当前标准 Writer 不会据此完成稀疏编码。
• 误区二：把 USTAR 当成所有 tar 工具的共同子集。它兼容性广，但不能表达稀疏文件。
• 误区三：读取时只看 Typeflag。GNU 与 PAX 的表达方式不同，应优先看 Reader 返回的 Header 和 SparseHoles。
• 误区四：认为读回 NUL 就等于磁盘上有洞。Reader 的字节语义和文件系统的物理分配是两件事。

结论

Go tar 写稀疏文件条目时，先做能力判断：archive/tar 适合读取稀疏条目，也适合生成不带 sparse map 的普通归档；它当前不负责把 SparseHoles 序列化为 GNU/PAX 稀疏格式。只要把“逻辑内容归档”和“保留稀疏编码”分开，Header.Size、空洞区间和格式兼容性就不会混在一起。

官方资料：

https://pkg.go.dev/archive/tar@go1.27.2

https://go.dev/src/archive/tar/writer.go

https://go.dev/src/archive/tar/format.go

相关问题

Header.SparseHoles 记录的是数据区还是空洞区？

记录的是空洞区，每项由偏移量和长度组成，表示该范围在逻辑文件中应按零字节读取。

FormatPAX 能不能保证 Go tar 写出稀疏归档？

不能。PAX 格式本身可以表达稀疏扩展，但 Go 标准 Writer 当前不会自动生成这部分 sparse map。

普通 tar 读取稀疏源文件会丢数据吗？

不会丢逻辑内容，但空洞会以零字节写入归档，所以归档可能比原文件占用更多空间。