Go 怎么为 ZIP 文件生成目录索引而不解压内容

如果业务只是展示 ZIP 里有哪些文件、判断某个路径是否存在，没必要把每个条目都解压到磁盘。Go 的 archive/zip 会先读取归档目录，zip.Reader.File 已经带有文件名、压缩方法和压缩前后大小等元数据。索引阶段遍历这些条目即可；只有真的要读某个文件时，才调用对应的 File.Open。

最稳妥的做法是把“目录扫描”和“内容读取”分成两层：用 OpenReader 加载目录，用 FileHeader 生成索引，不在扫描循环里打开文件内容。

ZIP 目录索引为什么不需要先解压

ZIP 归档的目录和压缩数据是两个概念。archive/zip 解析目录后，把每个条目放进 Reader.File；每个 *zip.File 内嵌了 FileHeader，因此在不读取正文的情况下就能拿到 Name、Method、CompressedSize64 和 UncompressedSize64。

这正适合做上传前检查、文件列表、后缀过滤和按路径定位。索引过程不需要创建临时目录，也不会因为某个大文件被解压而突然消耗大量磁盘空间。要注意，这里说的是“读取目录元数据”，不是验证每个条目的解压结果；完整性校验仍然属于内容读取阶段。

用 archive/zip 建立可检索的文件索引

下面的实现把 ZIP 条目转换为业务侧的 ZipEntry。扫描函数只做三件事：打开归档、复制元数据、按名称写入 map。它没有调用 f.Open()，所以不会为了生成目录而读取文件正文。

package main

import (
    "archive/zip"
    "fmt"
    "path"
    "strings"
)

type ZipEntry struct {
    Name            string
    CompressedSize  uint64
    UncompressedSize uint64
    Method          uint16
    IsDir           bool
}

func BuildIndex(filename string) (map[string]ZipEntry, error) {
    zr, err := zip.OpenReader(filename)
    if err != nil {
        return nil, fmt.Errorf("open zip: %w", err)
    }
    defer zr.Close() // 目录索引完成后释放底层文件句柄

    index := make(map[string]ZipEntry, len(zr.File))
    for _, f := range zr.File {
        name := path.Clean(strings.ReplaceAll(f.Name, "\\\\", "/"))
        if name == "." || strings.HasPrefix(name, "../") {
            continue // 目录索引不接受空路径和越界路径
        }
        index[f.Name] = ZipEntry{
            Name:             f.Name,
            CompressedSize:   f.CompressedSize64,
            UncompressedSize: f.UncompressedSize64,
            Method:           f.Method,
            IsDir:            strings.HasSuffix(f.Name, "/"),
        }
    }
    return index, nil
}

func main() {
    index, err := BuildIndex("assets.zip")
    if err != nil {
        panic(err)
    }
    if entry, ok := index["images/logo.svg"]; ok {
        fmt.Println(entry.Name, entry.UncompressedSize)
    }
}

这里用 path.Clean 做路径规则判断，但仍用原始的 f.Name 作为索引键，避免把归档内部名称悄悄改写后造成查找不一致。实际项目可以根据协议决定是拒绝反斜杠、重复路径，还是保留原名并单独记录告警。

按名称查找时，哪些字段值得保存

文件名是最直接的键，但目录页通常还要显示大小和压缩方式。使用 64 位字段可以避免大 ZIP 条目的尺寸溢出；Method 可以让调用方区分 Store 与压缩存储。目录项一般以 / 结尾，索引里保留它有助于前缀树或目录展开，但读取正文时不能把它误当成普通文件。

如果后续确实要读取某个文件，再从 Reader.File 保存的对象中调用 Open，并关闭返回的 io.ReadCloser。不要在建立全量索引时顺手读取所有正文，否则“目录索引不解压”的资源边界就失去了意义。

常见问题

遍历 Reader.File 会把 ZIP 内容全部解压吗？

不会。遍历得到的是条目和其头部元数据；读取正文通常从对应 File.Open 开始。

为什么索引里还要保留目录项？

目录项能支持目录树、前缀过滤和空目录展示。用名称是否以 / 结尾判断即可，不要把目录项当成可读文件。

可以只用 CompressedSize 吗？

不建议。32 位字段在大条目场景可能是截断标记，目录展示和策略判断应优先使用 CompressedSize64 与 UncompressedSize64。

什么时候才应该调用 File.Open？

当业务需要读取、解压或校验指定条目的正文时再调用；索引、查找和展示元数据不需要跨入这个边界。

把目录扫描和内容读取分成两条边界

Go 生成 ZIP 目录索引的关键不是寻找一个“快速解压”函数，而是只消费中央目录提供的元数据。用 OpenReader 打开后遍历 Reader.File，把 FileHeader 复制成稳定的业务索引，再按名称查询；需要正文时才单独打开条目。这样查目录的成本、磁盘占用和内容读取的风险都更容易控制。