Go tar.Writer.AddFS 打包目录时怎样处理嵌套文件系统错误

用 Go 把一个目录、embed.FS 或其他 fs.FS 打成 tar 时，最容易误判的是：看到“嵌套文件系统错误”，就以为 tar.Writer.AddFS 会替你跳过坏文件。实际并不是这样。AddFS 会从文件系统根目录开始遍历，遇到元数据读取、符号链接读取、文件打开、内容复制或 tar 头写入错误时，把错误交给调用方；它不会把失败条目静默吞掉。

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

处理这类错误的关键，是把“哪个路径出错”和“归档输出是否还能收尾”分开记录。用 errors.As 识别 *fs.PathError，再单独处理 AddFS 和 Close，通常比只打印一行字符串可靠。

AddFS 到底替你完成了什么

官方文档把 AddFS 的职责描述得很集中：从 fs.FS 的根开始遍历目录树，把每个文件加入 tar，并保持目录结构。当前实现内部使用 fs.WalkDir，回调中先读取 DirEntry.Info，再构造 tar.Header，普通文件随后通过 fsys.Open 和 io.Copy 写入。

这意味着它帮你处理的是“遍历和基本映射”，而不是业务层的容错策略。它不会判断某个文件是否可以忽略，也不会把目录打包失败改写成成功。需要部分成功时，应在更早的文件系统层过滤输入，或者改用自己的遍历逻辑。

输入文件系统要先选对根目录

os.DirFS 会把一个宿主机目录暴露成以相对路径为根的 fs.FS。这样写出的 tar 不会携带宿主机绝对路径，归档内的名称也更容易控制。下面的例子还展示了为什么要同时检查创建输出文件、添加文件和关闭归档的错误。

package main

import (
	"archive/tar"
	"errors"
	"fmt"
	"io/fs"
	"os"
)

func packDir(srcDir, outPath string) (err error) {
	// 让 fs.FS 的根对应 srcDir，避免把宿主机绝对路径写入归档。
	src := os.DirFS(srcDir)
	out, err := os.Create(outPath)
	if err != nil {
		return fmt.Errorf("create tar output: %w", err)
	}
	defer func() {
		// Close 负责落下 tar 尾部；它的错误不能覆盖前面已经发生的错误。
		if closeErr := out.Close(); err == nil && closeErr != nil {
			err = fmt.Errorf("close output: %w", closeErr)
		}
	}()

	tw := tar.NewWriter(out)
	if addErr := tw.AddFS(src); addErr != nil {
		// 先保留 AddFS 的真实错误，Close 仍由 defer 完成。
		return fmt.Errorf("add fs: %w", addErr)
	}
	if closeErr := tw.Close(); closeErr != nil {
		return fmt.Errorf("close tar: %w", closeErr)
	}
	return nil
}

func pathError(err error) *fs.PathError {
	// errors.As 能从多层 %w 包装中取出带路径的文件系统错误。
	var pe *fs.PathError
	if errors.As(err, &pe) {
		return pe
	}
	return nil
}

示例里的 defer 只负责宿主机输出文件的关闭，而 tw.Close 负责 tar 格式自身的尾部。两者不是同一个动作：前者是文件句柄生命周期，后者是归档格式收尾。

嵌套错误应该怎样定位到具体路径

当输入实现返回文件系统错误时，常见形态是 *fs.PathError。它通常包含操作名 Op、失败路径 Path 和底层原因 Err。不要只用字符串匹配错误文本，因为同一个路径可能对应打开失败、读取目录失败或读取文件失败。

func describeAddFSError(err error) string {
	// 用类型判断保留操作和路径，字符串只作为最后的展示层。
	var pe *fs.PathError
	if errors.As(err, &pe) {
		return fmt.Sprintf("op=%s path=%s cause=%v", pe.Op, pe.Path, pe.Err)
	}
	return err.Error()
}

AddFS 回调中还可能遇到符号链接目标读取失败、FileInfoHeader 构造失败、WriteHeader 写入失败以及 io.Copy 读取内容失败。它们的来源不同，但处理原则一致：保留原始错误，给文章、日志或上层接口补充“正在打包的任务”即可，不要把底层错误替换成模糊的“打包失败”。

为什么不能只处理 AddFS 而忽略 Close

tar 是流式格式。即使所有条目都成功写入，最终的补齐和结束标记仍可能在 Close 时写出失败；例如底层输出 writer 在收尾时返回错误。因此生产代码至少要区分三类信息：

• 输入错误：文件系统遍历、元数据、打开或读取失败，通常可以用 errors.As 定位路径。
• 归档写入错误：WriteHeader、io.Copy 或内部 writer 写出失败，说明输出可能已经不完整。
• 收尾错误：tw.Close 或输出文件 Close 失败，说明不能把文件当成完整归档交付。

如果 AddFS 先失败，通常不应继续把这个输出文件标记为可下载的完整 tar；可以保留错误日志和临时文件，待上层决定删除或重试。这里的“重试”是业务策略，不是 AddFS 内置行为。

哪些条目不会被 AddFS 自动加入

实现会把目录写成目录条目，把普通文件打开并复制；符号链接会尝试读取链接目标并写成链接条目。但其他既不是普通文件、也不是目录的类型会被拒绝，官方实现返回类似“cannot add non-regular file”的错误。不要把设备文件、FIFO 等特殊文件当作普通业务文件期待自动归档。

另外，fs.WalkDir 不会跟随目录中的符号链接；如果业务需要把链接目标内容复制进去，应先定义清楚安全边界，再用自定义遍历或显式读取策略完成，而不是把“跟随链接”当成 AddFS 的隐藏选项。

一个可执行的错误处理清单

常见问题

AddFS 会自动跳过读取失败的文件吗？

不会。读取、打开或元数据错误会结束这次遍历并返回错误。若要跳过某类错误，需要在自己的遍历回调里制定规则。

为什么 AddFS 成功后仍要调用 Close？

因为 AddFS 只负责添加条目，Close 负责写入 tar 归档尾部和补齐当前块；两者职责不同。

如何判断错误是不是某个文件路径导致的？

用 errors.As(err, &pathErr) 尝试取出 *fs.PathError，再读取 Path 和 Op，不要依赖错误字符串的固定格式。

可以直接把宿主机绝对路径传给 AddFS 吗？

AddFS 接收的是 fs.FS。更清晰的做法是先用 os.DirFS 选定归档根目录，让 tar 内部路径与宿主机路径解耦。

总结：tar.Writer.AddFS 适合完成“按 fs.FS 目录结构写入 tar”的通用工作，但错误策略仍属于调用方。把嵌套路径错误、归档写入错误和 Close 收尾错误分开处理，才能知道这个 tar 是在哪一层失效，也才能避免把不完整输出误交付给下游。