archive/tar 写入稀疏文件的头部字段配置

先给结论：当前 Go 标准库的 archive/tar.Writer 没有提供稀疏文件编码能力，因此不存在一组 tar.Header 字段，能让普通写入流程自动变成 GNU/PAX 稀疏条目。把 Format 改成 GNU、手工设置 TypeGNUSparse，或者只往 PAXRecords 填稀疏扩展键，都不能补齐稀疏映射和数据流转换。

这点很容易被误解，因为标准库的读取端能够识别若干 GNU/PAX 稀疏格式，但“能读”不等于“能写”。如果项目只是需要得到可解压的 tar 包，应按普通文件写入；如果必须保留洞区语义，应交给支持 --sparse 的 GNU tar，或实现并充分测试一套专用编码器。

一、稀疏文件真正需要编码什么

稀疏文件同时存在两种长度：逻辑长度是应用看到的文件大小；物理数据长度只统计真正占用块的非洞区。比如一个逻辑大小 20 GiB 的镜像，可能只有开头和末尾各写入了少量数据，其余区间读取时返回零，却不占用相同规模的磁盘块。

tar 要保留这种结构，归档中至少需要同时表达：

• 文件的逻辑长度，也就是恢复后文件应达到的大小；
• 每个真实数据段的偏移量和长度，即稀疏映射；
• 只包含真实数据段的物理数据流；
• 所选 GNU 或 PAX 稀疏版本要求的头部、扩展记录和 512 字节对齐。

普通 tar.Writer 只知道“头部声明了多少字节，接下来就必须收到多少字节”。它不会扫描零区，也不会把完整文件流自动改写成“稀疏映射 + 数据片段”。

二、Header 字段的作用边界

标准库源码中的限制也很明确：读取流程包含 GNU/PAX sparse 解析，而 Writer 端的稀疏支持仍未作为公开能力提供。实际工程中应把这个限制当成接口契约，而不是尝试通过未文档化字段组合绕过。

三、方案一：按普通条目写入，保证兼容性

如果只要求归档可移植、可解压，不强制恢复后的文件仍保持洞区，那么最稳妥的做法是把文件当普通条目写入。此时 Header.Size 必须使用逻辑大小，数据流也必须完整写满，包括洞区读取出来的零字节。

package archiveutil

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

func writeRegularEntry(tw *tar.Writer, srcPath, archiveName string) error {
	// 打开源文件，洞区在顺序读取时会表现为连续零字节。
	f, err := os.Open(srcPath)
	if err != nil {
		return fmt.Errorf("打开源文件失败: %w", err)
	}
	defer f.Close()

	// 读取逻辑大小和权限等元数据。
	info, err := f.Stat()
	if err != nil {
		return fmt.Errorf("读取文件信息失败: %w", err)
	}

	hdr, err := tar.FileInfoHeader(info, "")
	if err != nil {
		return fmt.Errorf("创建 tar 头失败: %w", err)
	}

	// 归档成员使用清理后的相对名称，不携带本机绝对路径。
	hdr.Name = path.Clean(archiveName)
	hdr.Typeflag = tar.TypeReg
	hdr.Size = info.Size()
	hdr.Format = tar.FormatPAX

	if err := tw.WriteHeader(hdr); err != nil {
		return fmt.Errorf("写入 tar 头失败: %w", err)
	}

	// 普通条目必须写满 Header.Size，不能只复制非零数据段。
	n, err := io.Copy(tw, f)
	if err != nil {
		return fmt.Errorf("写入条目数据失败: %w", err)
	}
	if n != hdr.Size {
		return fmt.Errorf("条目长度不一致: 已写 %d 字节，期望 %d 字节", n, hdr.Size)
	}
	return nil
}

这个方案的语义完全正确，但 tar 数据流会展开洞区。若后续再套 gzip、zstd 等压缩，连续零字节通常可以获得很高压缩率，不过生成 tar 中间流、管道传输量和处理时间仍按逻辑长度增长。对几十 GiB 甚至更大的稀疏镜像，这个代价可能不可接受。

四、三条工程路线怎么选

五、方案二：安全调用 GNU tar 的 --sparse

GNU tar 会检测文件中的洞区并写入相应稀疏表示。Go 程序调用它时，应使用参数数组而不是拼接 shell 字符串，并限制归档成员为受控相对路径。下面示例使用 POSIX/PAX 容器并开启稀疏检测：

package archiveutil

import (
	"context"
	"fmt"
	"os/exec"
	"path/filepath"
)

func createSparseArchive(
	ctx context.Context,
	archivePath string,
	baseDir string,
	name string,
) error {
	// 只接受本地相对路径，避免归档命令越出指定目录。
	if !filepath.IsLocal(name) {
		return fmt.Errorf("归档成员必须是安全的相对路径: %q", name)
	}

	// 参数逐项传递，不经过 shell 展开；双横线结束选项解析。
	cmd := exec.CommandContext(
		ctx,
		"tar",
		"--sparse",
		"--format=posix",
		"-cf",
		archivePath,
		"-C",
		baseDir,
		"--",
		name,
	)

	// 同时保留标准错误，便于定位工具缺失、权限和格式问题。
	output, err := cmd.CombinedOutput()
	if err != nil {
		return fmt.Errorf("GNU tar 创建稀疏归档失败: %w: %s", err, output)
	}
	return nil
}

生产环境还要注意三个细节。第一，并非所有名为 tar 的程序都实现 GNU 选项，macOS 常见实现与 GNU tar 并不完全相同，应在镜像或主机中明确安装、固定版本并记录路径。第二，输出归档最好放在输入树之外，避免把正在增长的归档再次打包。第三，命令超时或上游取消时，让 CommandContext 终止子进程，并把错误输出写入任务日志。

六、为什么手写 PAXRecords 不够

GNU/PAX 稀疏格式不是几个键值对那么简单。一个可互操作的编码器通常需要：

1. 扫描文件并得到按偏移排序、互不重叠的数据区间；
2. 根据稀疏版本编码逻辑大小、区间数量及每段偏移和长度；
3. 把头部中的物理数据大小与恢复后的逻辑大小正确区分；
4. 按映射顺序只写真实数据片段，并处理块对齐；
5. 同时用 GNU tar、bsdtar/libarchive 和 Go Reader 做交叉解包测试。

即使手工加入 GNU.sparse.* 一类 PAX 键，标准 Writer 仍会按照 Header.Size 约束后续写入长度，也不会替你跳转源文件、抽取数据片段或重写 tar 内部的物理尺寸。版本 0.0、0.1、1.0 的映射承载方式也不同，不能混用。

七、最常见的四类错误

1. Size 填逻辑大小，却只写非零片段

Writer 会认为条目尚未写完，在开始下一个条目或关闭时返回类似 archive/tar: missed writing N bytes 的错误。这不是填充策略问题，而是当前接口根本不知道这些缺失字节应当代表洞区。

2. Size 填物理数据大小，却写入完整文件

一旦实际写入超过头部声明长度，就会得到 archive/tar: write too long。把 Size 改小只是在破坏普通 tar 契约，并没有表达恢复后的逻辑长度。

3. 只设置 TypeGNUSparse

类型标记只是格式的一部分。缺少稀疏映射、逻辑大小和与映射匹配的数据流时，生成的条目会不完整，解包工具可能拒绝、截断或错误恢复。

4. 收集数据片段却忽略原始偏移

稀疏文件的意义来自“数据位于哪里”。把所有非零片段首尾相接只能得到压缩后的字节串，无法恢复原文件布局。区间偏移、长度和顺序必须作为协议数据一起编码。

八、读取端也要区分“内容正确”和“继续稀疏”

archive/tar.Reader 读取受支持的稀疏条目时，会让调用者看到完整逻辑内容，洞区表现为零字节。因此直接 io.Copy 到普通文件通常能得到内容正确的结果，但它可能实际写出所有零字节，不能保证目标文件继续保持稀疏。若恢复后也必须节省磁盘块，需要在输出端识别零区并使用 seek、打洞接口或平台专用能力。

九、可落地的配置结论

对 archive/tar 而言，普通写入时可以明确配置：

• Typeflag = tar.TypeReg；
• Size = 文件逻辑大小；
• Format = tar.FormatPAX 或项目需要的普通格式；
• 随后完整写入恰好 Size 字节。

但这些配置只会生成普通文件条目，并不会保留洞区。需要真正的 sparse tar 时，不要伪造 TypeGNUSparse 或仅注入扩展字段；优先使用部署中可控的 GNU tar --sparse。只有在外部工具不可用、格式要求固定且能承担跨实现测试成本时，才考虑专门的稀疏编码器。

参考资料

• Go archive/tar 包文档
• Go archive/tar 格式源码
• Go archive/tar Writer 源码
• GNU tar 稀疏文件手册