Go ZIP 条目名称含斜杠时怎么安全还原目录结构

解压 ZIP 时，条目名里的斜杠不是普通字符，而是归档内部的目录分隔符。安全做法是保留 f.Name 的正斜杠语义，先检查它是否为本地相对路径，再转换成当前操作系统的路径，最后才与目标根目录拼接。不要直接把未检查的名称交给 filepath.Join 或 os.Create。

结论很明确：用 filepath.IsLocal 拦截绝对路径、盘符路径和 .. 越界项；用 filepath.Localize 把 ZIP 的 slash-separated 名称转换为本地路径；尾部带 / 的条目只创建目录，其他条目才打开内容并复制到文件。

先把 ZIP 名称当成归档路径

archive/zip 返回的 FileHeader.Name 是归档内的名字，例如 assets/icons/logo.svg。这里的斜杠表达归档层级，不应先按当前系统分隔符拆开再自行拼接。名称以 / 结尾时，它描述的是目录条目，通常没有需要读取的文件内容；普通文件则通过 f.Open() 得到解压后的读取流。

文件名编码也属于元数据边界：FileHeader.NonUTF8 可以提示名称和注释不是 UTF-8，但它不是“把字节重新猜成某种编码”的解码器。应用若要兼容历史归档，应明确约定来源编码，不能因为看到中文乱码就把路径直接改写。

for _, f := range zr.File {
    // ZIP 内部统一使用 /；尾部斜杠表示目录条目。
    if strings.HasSuffix(f.Name, "/") {
        continue
    }

    // 文件内容必须通过条目打开，不能把名称当成本地文件读取。
    rc, err := f.Open()
    if err != nil {
        return fmt.Errorf("open zip entry %q: %w", f.Name, err)
    }
    rc.Close()
}

上面的循环只说明读取边界，真正落盘前还必须做路径检查。尤其不要用“去掉 ../ 字符串”代替安全判断，那会遗漏绝对路径、盘符和平台差异。

安全落盘要经过哪些判断

在 Go 1.23 及更新版本中，可以把步骤固定为“检查归档名、转换本地路径、拼接目标根目录、创建并复制”。filepath.IsLocal 会用词法分析判断路径是否为非空、非绝对且不含越界的 ..；filepath.Localize 接受 slash-separated 的有效路径，并在当前系统无法表示时返回错误。

func extractEntry(root string, f *zip.File) error {
    name := f.Name
    // 目录条目只参与目录创建，不进入文件内容复制分支。
    isDir := strings.HasSuffix(name, "/")
    if !filepath.IsLocal(name) {
        return fmt.Errorf("拒绝不安全的 ZIP 条目 %q", name)
    }

    // Localize 把归档路径转换为当前操作系统可接受的路径。
    localName, err := filepath.Localize(name)
    if err != nil {
        return fmt.Errorf("本地化 ZIP 条目 %q 失败: %w", name, err)
    }
    target := filepath.Join(root, localName)

    if isDir {
        // MkdirAll 让显式目录条目和隐式父目录都能正常落盘。
        if err := os.MkdirAll(target, 0o755); err != nil {
            return fmt.Errorf("创建目录 %q 失败: %w", name, err)
        }
        return nil
    }

    // 文件父目录可能没有显式目录条目，先补齐它。
    if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
        return fmt.Errorf("创建父目录 %q 失败: %w", name, err)
    }
    rc, err := f.Open()
    if err != nil {
        return fmt.Errorf("打开 ZIP 条目 %q 失败: %w", name, err)
    }
    defer rc.Close()

    out, err := os.Create(target)
    if err != nil {
        return fmt.Errorf("创建目标文件 %q 失败: %w", name, err)
    }
    defer out.Close()

    // 流式复制避免把整个条目一次性读入内存。
    if _, err := io.Copy(out, rc); err != nil {
        return fmt.Errorf("写入 ZIP 条目 %q 失败: %w", name, err)
    }
    return nil
}

这里的 Join 负责组合已经通过检查的相对路径，不是安全检查本身。官方文档也提醒，IsLocal 不会考虑符号链接的影响。如果解压目录可能被其他进程写入，或目录中已有可控符号链接，应在更严格的文件系统 API 与部署隔离策略下处理，不能只靠字符串判断。

把目录、编码和读取错误分开记录

故障复盘时，最容易混淆的是“目录没有还原”“名称乱码”和“文件打不开”。它们发生在不同位置，记录方式也应不同。

如果使用 zip.OpenReader 或 zip.NewReader 时得到 zip.ErrInsecurePath，应把它当作归档中存在非本地名称或反斜杠名称的信号。除非业务已经有明确的隔离和兼容方案，否则不要为了“尽量解压”而忽略这个错误。

常见问题

为什么不能直接用 strings.ReplaceAll 把斜杠换成系统分隔符？

因为替换只改变字符，不会判断绝对路径、盘符、父目录越界和当前系统能否表示该名称。ZIP 名称先经过 IsLocal，再交给 Localize，语义更清楚。

没有目录条目，文件还能还原到多级目录吗？

可以。很多归档只写入文件项，例如 a/b/c.txt，没有单独的 a/、a/b/。解压文件前用 MkdirAll(filepath.Dir(target)) 补齐父目录即可。