Go archive/tar Writer.AddFS 怎样把文件系统写入 tar 归档

把一棵目录树打成 tar 时，最容易出错的地方不是 tar.NewWriter，而是手写文件遍历、路径拼接和 Header。Go 的 archive/tar.Writer.AddFS 可以直接接收 fs.FS，从文件系统根开始遍历，并把目录结构写入归档。常见做法是先用 os.DirFS 把一个本地目录变成文件系统视图，再让 AddFS 负责写入。

先记住三个边界：os.DirFS 决定归档根目录，AddFS 负责遍历和写入，Close 负责 tar 的收尾。它们的错误要分别处理，不能只检查最后一个返回值。

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

先把本地目录转换成清晰的 fs.FS

生产任务通常已经有一个确定的输入目录，例如导出临时目录、构建产物目录或备份工作区。os.DirFS(root) 会把这个目录作为文件系统视图的根；归档内的路径从这个根开始计算，不需要把机器上的绝对路径写进 tar。这样既减少路径泄露，也让归档在另一台机器上解包时保持稳定的相对结构。

这里的根目录要在业务层先确定并限制范围。不要把用户可控的任意绝对路径直接传入归档逻辑；如果输入来自上传或任务参数，应先映射到受控工作目录，再创建 DirFS。

用 AddFS 保持目录结构写入 tar

最小实现只需要创建输出文件、创建 tar writer、调用 AddFS，最后关闭 writer。示例把 ./export-input 作为归档根，最终写出 ./export.tar。代码中的注释说明了每个错误边界；示例是静态代码，不是运行截图或本机执行证据。

package main

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

func buildTar(root, output string) error {
	// 先创建输出文件，失败时不要继续构造 tar writer。
	out, err := os.Create(output)
	if err != nil {
		return fmt.Errorf("create tar file: %w", err)
	}
	defer func() {
		// Close 的错误由显式调用负责返回，这里只释放文件描述符。
		_ = out.Close()
	}()

	// DirFS 把 root 设为归档根，避免把本机绝对路径写入条目名。
	input := os.DirFS(root)
	tw := tar.NewWriter(out)
	if err := tw.AddFS(input); err != nil {
		// AddFS 可能在遍历、打开或写入某个条目时失败。
		return fmt.Errorf("add filesystem to tar: %w", err)
	}
	if err := tw.Close(); err != nil {
		// Close 会写入 tar 收尾信息，失败时输出文件不能视为完整归档。
		return fmt.Errorf("close tar writer: %w", err)
	}
	return nil
}

func main() {
	if err := buildTar("./export-input", "./export.tar"); err != nil {
		// 调用方应记录任务标识和输入根目录，便于定位失败条目。
		fmt.Println(err)
		return
	}
	fmt.Println("tar archive created")
}

AddFS 接收的是 fs.FS，因此同样的归档函数也可以接收嵌入文件系统或测试文件系统。对本地目录来说，os.DirFS 是边界适配器；它不会改变文件内容，只负责把目录树暴露为统一的 FS 接口。

不要把 AddFS 错误和 Close 错误混在一起

AddFS 的失败通常发生在遍历目录、打开文件或向输出 writer 写入条目时；它返回后，归档可能只写了一部分。即使 AddFS 成功，也要检查 tw.Close()，因为 tar writer 还需要完成当前条目的填充和归档尾部写入。

输出文件本身也需要关闭。上面的示例让显式的 tw.Close() 先完成 tar 收尾，再由 defer 释放文件描述符；这样不会把真正的归档错误隐藏在延迟关闭里。若业务需要把结果交给下游，只有所有步骤成功后才应把临时文件改名为最终文件。

生产环境还要收紧目录、权限和日志

归档逻辑本身很短，但生产问题往往出在边界条件。第一，输入根目录应该是任务专属目录，避免把同机其他文件带入归档。第二，输出文件先写临时名称，成功后再原子替换，失败时清理临时文件。第三，日志至少记录任务 ID、输入根目录的业务标识、输出临时文件和失败阶段，不要把用户文件内容直接写入日志。

可以按下面的检查顺序复查：

• 输入目录是否已经被映射到受控工作区，且没有把绝对路径当作条目名。
• AddFS 和 Close 是否分别有错误包装，失败时是否阻止下游读取半成品。
• 成功归档是否只在关闭 writer 后发布，临时文件是否按失败路径清理。

常见问题

AddFS 会把本地绝对路径写进 tar 吗？

用 os.DirFS(root) 作为输入时，归档路径从这个 FS 根开始表达，调用方不需要把本地绝对路径拼进条目名。最终条目仍应由业务规则限制和复查。

为什么 AddFS 成功后还要 Close？

因为 Close 负责完成 tar writer 的收尾。没有成功关闭 writer，输出文件不能按完整归档交给下游。

小结

使用 Writer.AddFS 的关键不是记住一行 API，而是把职责拆开：os.DirFS 定义输入根，AddFS 遍历并写入目录树，Close 完成归档收尾。按阶段记录错误，并在完整成功后发布输出文件，才能避免路径泄露和半成品 tar 进入下游流程。