Go archive/tar 如何控制目录路径

我第一次用 Go 的 archive/tar 打包目录时，最容易误判的地方不是压缩，而是路径：磁盘上明明是 root/app/config.yaml，归档里却出现了绝对路径，或者只剩下 config.yaml。真正控制 tar 内部目录层级的字段是 tar.Header.Name。把磁盘路径先相对化，再把这个结果写回 Header，就能稳定得到 app/config.yaml。

归档内路径由 Header.Name 决定；推荐以打包根目录为基准调用 filepath.Rel，再用 filepath.ToSlash 统一分隔符。解压到哪个磁盘目录，是读取阶段的另一件事。

先分清三种路径，问题就不会绕在一起

这次我把路径拆成三个名字：磁盘路径是 /srv/release/app/config.yaml；归档内路径是 app/config.yaml；解压目标路径可能是 /tmp/unpack。archive/tar 写入时只认识第二个名字，也就是 Header 的 Name 字段。tar.Writer 不会替你推断“希望归档保留哪一级目录”。

tar.FileInfoHeader 会根据 fs.FileInfo 生成一个部分填充的 Header。官方文档特别说明，文件信息中的 Name() 通常只有基础名；目录还会自动带上斜杠。因此，想保留多级目录，就要在调用它之后显式设置 header.Name。

用相对路径控制 tar 内部目录层级

核心写法是把 root 设为归档根目录。遍历得到每个文件后，用 filepath.Rel(root, path) 去掉本机前缀，再把结果转换成归档更适合使用的斜杠路径。下面的示例只展示打包逻辑，代码中的输出是说明性结果，不代表某台机器已经执行。

package main

import (
    "archive/tar"
    "fmt"
    "io"
    "io/fs"
    "os"
    "path/filepath"
    "strings"
)

func addEntry(tw *tar.Writer, root, path string, d fs.DirEntry) error {
    // 归档名只保留 root 下的相对部分，避免写入本机绝对路径。
    rel, err := filepath.Rel(root, path)
    if err != nil {
        return fmt.Errorf("计算相对路径: %w", err)
    }
    if rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
        // 拒绝空名称和逃出 root 的路径，防止归档结构失去边界。
        return fmt.Errorf("非法归档路径: %q", rel)
    }
    archiveName := filepath.ToSlash(rel)

    info, err := d.Info()
    if err != nil {
        return fmt.Errorf("读取文件信息: %w", err)
    }
    header, err := tar.FileInfoHeader(info, "")
    if err != nil {
        return fmt.Errorf("创建 tar 头: %w", err)
    }
    // FileInfoHeader 只提供基础名；这里覆盖成期望的目录层级。
    header.Name = archiveName
    if d.IsDir() && !strings.HasSuffix(header.Name, "/") {
        header.Name += "/"
    }
    if err := tw.WriteHeader(header); err != nil {
        return fmt.Errorf("写入 tar 头: %w", err)
    }
    if d.IsDir() {
        return nil
    }

    f, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("打开文件: %w", err)
    }
    defer f.Close() // 每个条目完成后释放文件描述符。
    if _, err := io.Copy(tw, f); err != nil {
        return fmt.Errorf("写入文件内容: %w", err)
    }
    return nil
}

如果遍历根目录本身，通常可以跳过 rel == "." 的根条目，让归档从 app/ 开始；如果业务确实要保留顶层目录，则应给它一个明确的归档名，而不是直接把点号写进去。这个选择会影响解压后的目录层级，最好在接口文档中固定下来。

目录、文件和符号链接的路径策略要统一

目录条目建议保留结尾斜杠，便于其他 tar 工具识别层级；普通文件不需要补斜杠。符号链接则要额外传入链接目标，不能把它当作普通文件打开后复制。若项目只允许普通文件和目录，遍历时可以明确拒绝符号链接，减少路径策略的分支。

我实际更倾向于把路径策略集中在一个函数里：所有入口都先做相对化、斜杠化和边界检查，再交给 WriteHeader。这样不会出现目录用一套规则、文件又偷偷保留另一套前缀的情况。

写入前的四项检查，能挡住大多数路径坑

第一，禁止把 filepath.Abs 的结果直接赋给 Header.Name；那会把机器目录暴露给归档消费者。第二，跨平台项目不要直接把系统分隔符当成归档分隔符，统一使用 filepath.ToSlash。第三，Rel 的结果要检查 ..，尤其是路径来自用户输入或多个根目录拼接时。第四，解压端仍要再次检查条目名是否为本地安全路径，写入端的约束不能替代读取端的防护。

可以把最终规则压缩成一句检查清单：归档名是否相对、是否使用斜杠、目录是否有尾斜杠、是否拒绝越界、是否按条目类型决定读取方式。只要这五项稳定，目录路径通常就不会再靠“换一个工作目录”碰运气。

常见问题

为什么 FileInfoHeader 后还要改 Header.Name？

因为文件信息通常只能提供基础名，而归档需要的可能是多级相对路径。Header 生成后覆盖 Name，是保留目录层级的标准做法。

把路径改成斜杠会不会影响 Windows 文件？

不会影响磁盘读取。磁盘路径仍使用 filepath 处理，只有写入 tar 的逻辑名称使用 ToSlash，便于归档在不同系统间交换。

控制了 Header.Name，解压就一定安全吗？

不一定。写入端应避免生成越界路径，解压端仍需检查条目名并限制目标目录；两边是独立的安全边界。