Go 解压 ZIP 时怎么区分目录条目和空文件

Go 解压 ZIP 时，不要用“文件内容是否为空”来判断目录。目录条目应该看 FileHeader.IsDir()；普通文件即使大小为 0，也仍然是文件，应该创建出来。archive/zip 已经把条目元数据放在 zip.File 中，循环时先分流目录，再打开文件，是最稳定的写法。

先按 IsDir 判断目录，空文件仍然要落盘

FileHeader.Name 以斜杠结尾时表示目录，IsDir() 会把这个元数据转换成目录判断。空文件虽然没有内容，但它的名称不是目录形式，不能因为大小为 0 就跳过。下面的循环展示了两条分支：目录只负责创建目录，文件分支负责创建文件并复制内容。

package main

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

func extractOne(z *zip.File, root string) error {
    // 先清理相对路径，后面还要单独检查是否越出 root。
    name := filepath.Clean(filepath.FromSlash(z.Name))
    if name == "." || filepath.IsAbs(name) || name == ".." ||
        len(name) > 3 && name[:3] == ".."+string(os.PathSeparator) {
        return fmt.Errorf("条目 %q 路径不安全", z.Name)
    }
    dst := filepath.Join(root, name)

    if z.FileHeader.IsDir() {
        // 目录条目可能没有数据，只创建对应目录。
        if err := os.MkdirAll(dst, 0755); err != nil {
            return fmt.Errorf("创建目录 %q: %w", z.Name, err)
        }
        return nil
    }

    // 空文件也会进入这里，创建后复制 0 字节仍能保留文件。
    if err := os.MkdirAll(filepath.Dir(dst), 0755); err != nil {
        return fmt.Errorf("创建父目录 %q: %w", z.Name, err)
    }
    out, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0644)
    if err != nil {
        return fmt.Errorf("创建文件 %q: %w", z.Name, err)
    }
    defer out.Close()

    in, err := z.Open()
    if err != nil {
        return fmt.Errorf("打开条目 %q: %w", z.Name, err)
    }
    defer in.Close()
    if _, err = io.Copy(out, in); err != nil {
        return fmt.Errorf("复制条目 %q: %w", z.Name, err)
    }
    return nil
}

这里的关键不是“有没有数据”，而是条目类型。目录分支不会调用 Open；空文件分支会正常打开，io.Copy 返回 0 也不代表出错。生产代码还可以把 Close 的错误纳入统一返回策略，示例先突出条目读取错误的定位。

名称和读取错误要分层处理

NonUTF8 表示 ZIP 条目的名称或注释不是 UTF-8。它是名称元数据提示，不是“这个条目就是目录”或“必须把字节按某种编码重解码”的结论。通常先使用 Go 解析后的 Name，将编码策略和文件落盘策略分开，避免把名称显示问题混入目录判断。

错误信息最好始终带上原始条目名。例如 打开条目 "资料/空白.txt": checksum error 比单独返回 checksum error 更容易定位。File.Open 负责透明解压并提供内容读取器，复制阶段则可能暴露校验和或底层 I/O 问题；两处都应该保留上下文。

解压前后的检查清单

• 用 z.FileHeader.IsDir() 判断目录，不用文件大小判断。
• 对 Name 做相对路径和目标根目录检查，避免条目越界。
• 目录使用 MkdirAll；文件先创建父目录，再 Open、复制和关闭。
• 每个错误都带上 ZIP 条目名，区分创建、打开和复制阶段。
• 如果业务必须转换非 UTF-8 文件名，先明确来源编码，再单独替换名称；不要把 NonUTF8 当作自动转换开关。

常见问题

为什么不能用 UncompressedSize64 判断目录？

因为空文件的未压缩大小同样是 0。目录的可靠信号是目录条目元数据，使用 IsDir() 才不会跳过合法空文件。

目录条目一定要调用 Open 吗？

不需要。目录的职责是建立目标目录；文件分支才需要打开内容读取器。

File.Open 返回错误时应该继续解压吗？

取决于业务是否允许部分结果。至少要记录条目名和阶段；配置文件、代码包等不可缺失场景应立即返回，批量导入则可以收集错误后统一报告。