Go archive/tar 怎么保留目录结构解包到指定目录

用 Go 解包 tar 时，目录结构能不能保留，关键不在于把条目名直接交给 filepath.Join，而在于先确认这个名字确实只能落在目标目录里。一个稳妥的实现是：用 tar.Reader.Next 逐个读取条目，拒绝绝对路径和包含 .. 的非本地路径，再按条目类型创建目录或写入普通文件。

下面的代码只覆盖普通目录和普通文件，适合把归档展开到一个明确的目标目录；符号链接、硬链接和权限完整恢复需要单独设计安全策略。

最小安全边界是：先用 filepath.IsLocal(hdr.Name) 判断条目名，再用 filepath.Join(dest, filepath.FromSlash(hdr.Name)) 形成目标路径；不通过的条目直接拒绝，不要试图用清理后的路径“修正”它。

先把 tar 条目名限制在目标目录内

archive/tar 的 Reader 是顺序读取器，每次 Next 返回一个 Header，当前条目的数据则由这个 Reader 继续提供。Header.Name 可能来自不可信的归档文件，因此要先做路径判断。

Go 提供的 filepath.IsLocal 可用于拒绝绝对路径、空路径和包含父级跳转的非本地路径。通过后再把 tar 使用的斜杠路径转换成当前系统的路径分隔符，交给 filepath.Join 拼到目标目录下。这里不要先调用 filepath.Clean 再放行，因为清理会把异常路径变成“看起来正常”的路径，掩盖输入问题。

用 TypeDir 与 MkdirAll 还原目录树

目录条目通常以 tar.TypeDir 标识。遇到它时直接对目标路径调用 os.MkdirAll，即使父目录还没有出现，也能把整棵目录树补齐。普通文件则不能只创建文件本身，因为归档可能先出现文件、后出现目录，或者目录条目本身被某些工具省略，所以写文件前统一创建 filepath.Dir(target) 更稳妥。

package main

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

func extractTar(r io.Reader, dest string) error {
    tr := tar.NewReader(r)
    for {
        hdr, err := tr.Next()
        if err == io.EOF {
            return nil // 没有更多条目，解包正常结束。
        }
        if err != nil {
            return fmt.Errorf("读取 tar 条目失败: %w", err)
        }
        if !filepath.IsLocal(hdr.Name) {
            return fmt.Errorf("拒绝不安全条目路径: %q", hdr.Name)
        }

        // tar 的路径使用斜杠，转换后再拼接到固定目标目录。
        target := filepath.Join(dest, filepath.FromSlash(hdr.Name))
        switch hdr.Typeflag {
        case tar.TypeDir:
            // 目录条目负责建立层级，权限按业务策略另行决定。
            if err := os.MkdirAll(target, 0755); err != nil {
                return fmt.Errorf("创建目录 %q 失败: %w", target, err)
            }
        case tar.TypeReg, 0:
            // 文件条目先补齐父目录，兼容缺少显式目录条目的归档。
            if err := os.MkdirAll(filepath.Dir(target), 0755); err != nil {
                return fmt.Errorf("创建父目录失败: %w", err)
            }
            mode := os.FileMode(hdr.Mode).Perm()
            if mode == 0 {
                mode = 0644 // 归档没有可用权限时使用保守默认值。
            }
            f, err := os.OpenFile(target, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, mode)
            if err != nil {
                return fmt.Errorf("创建文件 %q 失败: %w", target, err)
            }
            _, copyErr := io.Copy(f, tr) // 只消费当前条目的数据。
            closeErr := f.Close()        // 复制成功也必须释放文件描述符。
            if copyErr != nil {
                return fmt.Errorf("写入文件 %q 失败: %w", target, copyErr)
            }
            if closeErr != nil {
                return fmt.Errorf("关闭文件 %q 失败: %w", target, closeErr)
            }
        default:
            // 不自动落地链接、设备或 FIFO，避免扩大解包的系统权限边界。
            return fmt.Errorf("暂不支持 tar 条目类型 %d: %q", hdr.Typeflag, hdr.Name)
        }
    }
}

代码中没有把当前条目的字节读进一个大切片，而是让 io.Copy 从 tar.Reader 流向目标文件。下一次调用 Next 时，Reader 会定位到下一个条目；如果当前文件没有完全消费，Next 也会丢弃剩余数据，但显式复制完整内容更容易发现写入错误。

把普通文件内容写入对应路径

真正写入时要关注三个资源：目标目录、当前文件和当前 tar 条目。目标目录应由调用方创建并控制权限；文件句柄必须在每个条目内关闭；tr 只能在当前条目范围内读取，不能在循环外异步保存它的引用。

os.O_TRUNC 适合“解包结果覆盖到指定目录”的场景，但如果目标目录里存在不应被覆盖的文件，应改成 os.O_EXCL 或先做冲突策略。归档中的 hdr.Mode 也不应不加限制地恢复到生产目录，示例只保留权限位，并在缺失时使用普通文件的保守默认值。

处理链接、错误和解包边界

从 Go 的 archive/tar 文档看，Next 可以在特定 GODEBUG 配置下返回 ErrInsecurePath，而且这个检查只针对文件名，不会替你验证链接目标。因此应用层仍应保留自己的路径拒绝策略，并默认不创建链接。对于来自上传接口的 tar，还应在解包外层设置输入大小、超时和磁盘配额；这些不属于目录树逻辑，却决定了解包服务能否稳定运行。

相关问题

为什么不能只用 filepath.Clean 处理条目名？

Clean 会把 a/../b 变成 b，但这不代表原始归档路径可信。先用 IsLocal 判断，拒绝异常输入，再拼接目标路径，边界更清楚。

tar 里的目录条目缺失还能保留层级吗？

可以。普通文件写入前调用 MkdirAll(filepath.Dir(target))，即使归档没有单独的目录条目，也能按文件路径补齐父目录。

需要保留原始权限怎么办？

先定义允许恢复的权限范围，再对 hdr.Mode 做掩码和策略限制。不要直接恢复特殊权限、设备节点或链接；生产解包通常优先保证路径和对象类型安全。