Go archive/zip 大文件为什么报 directory size overflow

我第一次遇到 directory size overflow，直觉是“某个文件超过 4GB 了”。后来拆开 ZIP 结构才发现，报错里的 directory 通常不是磁盘目录，而是 ZIP 文件末尾的 central directory（中心目录）：它记录每个条目的名称、压缩大小、原始大小和数据偏移。条目很多、文件很大或归档起始偏移很高时，中心目录自己的 32 位字段可能越界。

先看 directory size overflow 到底溢出了哪一层

传统 ZIP 的末尾记录用 32 位字段保存中心目录大小和偏移，最大值接近 4GiB。中心目录并不是压缩数据本身，而是一组目录项；每个条目都会带上固定头、文件名、扩展字段和注释。因此，即使每个文件都没有超过 4GiB，几十万条目或很长的文件名也可能让中心目录先达到边界。

Go 官方 archive/zip 文档明确区分了 32 位和 64 位尺寸字段：需要 ZIP64 时，32 位字段使用占位值，真实值放在 64 位字段中。当前 Writer 在 Close 阶段统计中心目录的记录数、大小和偏移，满足 ZIP64 条件就写入 Zip64 End of Central Directory 和 locator。所以，看到这个错误时不要先把文件拆小，先确认实际生成者是不是当前标准库，或者是不是某个旧的 ZIP writer、手工拼接工具在写普通 EOCD。

用 FileHeader 和 Close 把 Zip64 写完整

我的处理顺序是先把普通流式写入跑通，再检查是否使用了 CreateRaw。用 Create 时，Go 负责 Deflate 和数据描述符，调用方不需要提前猜压缩后大小；而 CreateRaw 代表你已经准备好了压缩字节，头部的压缩大小、原始大小和 CRC32 必须与实际数据一致。若尺寸超过 32 位，应该使用 CompressedSize64 和 UncompressedSize64，不要只给已经过时的 32 位字段赋值。

package main

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

func writeZip(dst string, files []string) error {
    // 创建输出文件；底层文件的 Close 不能替代 zip.Writer.Close。
    out, err := os.Create(dst)
    if err != nil {
        return err
    }
    defer out.Close()

    zw := zip.NewWriter(out)
    for _, name := range files {
        // Create 适合未知压缩后尺寸的流式写入，标准库负责目录元数据。
        entry, err := zw.Create(name)
        if err != nil {
            return fmt.Errorf("create %s: %w", name, err)
        }
        src, err := os.Open(name)
        if err != nil {
            return fmt.Errorf("open %s: %w", name, err)
        }
        // Copy 的错误必须向上传递，否则归档可能只写入半个条目。
        _, copyErr := io.Copy(entry, src)
        closeErr := src.Close()
        if copyErr != nil {
            return fmt.Errorf("copy %s: %w", name, copyErr)
        }
        if closeErr != nil {
            return fmt.Errorf("close %s: %w", name, closeErr)
        }
    }
    // 中心目录在这里才落盘；大归档不能省略这个错误检查。
    if err := zw.Close(); err != nil {
        return fmt.Errorf("close zip: %w", err)
    }
    return nil
}

这个示例的关键不是“压缩级别更高”，而是让同一个 Writer 负责条目和中心目录，并把最终的 Close 当作发布结果的一部分。Go 文档也说明，Writer.Close 只结束 ZIP 写入，不会替你关闭底层 io.Writer。

大包排查清单：先修写入端，再看消费端

还有一个容易误判的边界：压缩后大小变小，不会让中心目录消失；中心目录仍要保存每个文件的元数据。相反，减少重复条目、缩短路径、拆成多个 Zip，才会直接减少目录记录压力。若接收方是老旧解压库，Zip64 即使格式正确也可能不被支持，这时应该把兼容性当成接口约束，而不是继续修改 FileHeader 里的数字。

相关问题

directory size 是磁盘目录的大小吗？

不是。它通常指 ZIP 中心目录的字节数，包含条目索引和元数据。

只把 UncompressedSize 改成最大值能解决吗？

不能。那会让头部看起来像 ZIP64，却可能与实际数据和中心目录不一致；应使用标准 Writer，或完整维护 Zip64 字段。

为什么一定要检查 zw.Close？

中心目录在 Close 阶段写入，之前的文件内容写成功，不代表 ZIP 已经完整封口。

排查这类错误时，我现在固定先问三件事：溢出的是单项尺寸还是中心目录，写入端是否真的会生成 Zip64，最后的 Close 错误有没有被吞掉。三项都明确后，再决定升级库、拆分归档还是更换消费端，通常比盲目降低压缩级别更快。