Go archive/zip校验压缩包内文件名的安全边界

Go 读取 ZIP 时，最容易被忽略的不是压缩算法，而是条目名称。zip.FileHeader.Name 来自外部压缩包，不能未经检查就和输出目录拼接；稳妥做法是先拒绝绝对路径、父目录跳转、反斜杠和盘符前缀，再决定是否打开内容或创建本地文件。这样处理，目录穿越风险和跨平台路径差异都会落在一个清晰的边界内。

先定义 ZIP 条目名称的安全边界

archive/zip 的 FileHeader.Name 要求名称是相对路径，不能以盘符开头，并且使用正斜杠。对服务端解压来说，还要把“最终写到哪个目录”纳入判断：/tmp/result、../secret.txt、a/../../secret、C:\\temp\\x.txt 和包含反斜杠的名称都不应直接落盘。目录条目如 assets/ 可以保留，但仍要经过同一套名称检查。

这里建议把“合法”定义得比库的最低接受范围更窄：名称必须非空、使用正斜杠、不能是 . 或 ..，清理后还要与原名称一致。这样可以避免同一个文件以 docs/../readme.md 之类的多种写法进入后续逻辑，日志、去重和权限检查也更容易保持一致。

用一个校验函数锁住路径规则

校验函数只负责判断条目名称，不负责创建目录或写入文件。使用 path.Clean 处理 ZIP 的正斜杠语义，再用 filepath.IsLocal 补上当前 Go 运行平台对本地路径的判断；另外显式拦截 Windows 盘符前缀，避免代码换到不同系统后规则变松。

package main

import (
    "fmt"
    "path"
    "path/filepath"
    "strings"
)

func validateZipName(name string) error {
    // ZIP 条目统一按正斜杠解释，反斜杠直接拒绝，避免跨平台含义不一致。
    if name == "" || strings.ContainsRune(name, '\\') {
        return fmt.Errorf("invalid zip entry name: %q", name)
    }
    // 盘符前缀不属于可移植的相对 ZIP 路径，例如 C:tmp/a.txt。
    if len(name) >= 2 && ((name[0] >= 'A' && name[0] = 'a' && name[0] 

这个函数没有把名称转换成操作系统路径，也没有用字符串替换“修复”危险片段。原因很简单：替换后得到的名字可能和压缩包内的原始语义不一致，调用方还可能在别处继续使用未经检查的原值。更好的约定是：校验成功后才把同一个规范名称交给后续流程，校验失败就记录条目名并跳过。

把校验放在打开和落盘之前

遍历 zip.Reader.File 时，先检查每个 f.Name，目录条目可以只建立目录映射，普通文件才打开内容。不要先 f.Open()、读取一部分内容，再回头判断文件名；也不要直接执行 filepath.Join(outputRoot, f.Name) 就写文件。即使 Join 看起来生成了一个“正常路径”，安全决策也应该基于条目名和输出根目录的边界。

for _, f := range zr.File {
    // 先检查外部条目名，拒绝不安全名称后才进入内容处理。
    if err := validateZipName(f.Name); err != nil {
        return fmt.Errorf("reject %q: %w", f.Name, err)
    }
    if strings.HasSuffix(f.Name, "/") {
        // 目录条目只记录目录意图，不把它当作普通文件读取。
        continue
    }
    rc, err := f.Open()
    if err != nil {
        return fmt.Errorf("open %q: %w", f.Name, err)
    }
    // 读取完成后立即关闭当前条目，避免大量条目占住资源。
    _, copyErr := io.Copy(dst, rc)
    closeErr := rc.Close()
    if copyErr != nil {
        return fmt.Errorf("read %q: %w", f.Name, copyErr)
    }
    if closeErr != nil {
        return fmt.Errorf("close %q: %w", f.Name, closeErr)
    }
}

上面的片段展示的是处理顺序，实际项目要为每个条目创建独立的目标文件，并把 dst 绑定到校验过的输出路径。还应设置单个文件大小、总解压大小和条目数量上限；这些属于资源消耗控制，不能被“文件名校验通过”替代。

正确区分 ErrInsecurePath 与普通读取错误

当前 archive/zip 文档说明：当 GODEBUG=zipinsecurepath=0 时，如果条目包含非本地名称或反斜杠，OpenReader、NewReader 可能返回带有 zip.ErrInsecurePath 的 reader。这个错误和 ZIP 格式损坏、校验和错误不是一回事。生产服务通常应记录并拒绝这类包；只有明确知道兼容风险、且仍会对每个条目执行自己的校验时，才考虑继续使用返回的 reader。

常见问题

只调用 filepath.IsLocal 就够了吗？

不够。ZIP 格式使用正斜杠，而 filepath.IsLocal 还受运行平台语义影响。把反斜杠、盘符前缀、规范化变化和输出根目录检查写成明确规则，跨平台迁移时更容易复核。

可以把 ../ 替换为空字符串后继续解压吗？

不建议。替换会改变原始名称并隐藏输入问题，可能让日志、去重和权限判断使用不同字符串。更安全的策略是拒绝该条目，并让上传方重新生成压缩包。

目录条目需要单独校验吗？

需要。目录名同样来自压缩包，若直接用它创建本地目录，仍可能影响输出根目录之外的位置。目录条目可以不读取内容，但不能跳过名称校验。