Go archive/zip 出错时怎么排查损坏头

Go 的 archive/zip 报“ZIP 头损坏”时，先别急着把整个文件判定为不可用。读取一个归档至少经过中央目录、条目的本地文件头和压缩内容三个边界：目录能读通，不代表每个条目的本地头完整；本地头能定位，也不代表内容通过 CRC 校验。实际排查时，围绕 zip.ErrFormat、zip.ErrChecksum 和具体条目名记录错误，通常比只打印“打开失败”快得多。

先区分目录解析和单个条目损坏

zip.OpenReader 负责建立 Reader 并读取归档索引，索引中的每个 File 又带着自己的 FileHeader。真正访问文件内容时，File.Open 还要回到 ZIP 中找到对应的本地文件头，确认签名、字段长度和数据位置。于是一个归档可能出现两种看似相同的现象：整个归档连索引都读不出来，或者索引正常但某个条目一打开就报格式错误。

因此第一步要保留条目名和调用位置。只打印 zip.OpenReader 的返回值，会丢掉“第几个文件有问题”这一关键信息；而只遍历 Reader.File，又可能只证明中央目录存在。

用 ErrFormat 与 ErrChecksum 缩小范围

Go 标准库已经把常见失败拆成可比较的错误值。可以把每个条目读到末尾，区分头部定位失败、压缩算法不支持和内容校验失败：

package main

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

func inspectZip(path string) error {
    zr, err := zip.OpenReader(path)
    if err != nil {
        // 归档索引都无法建立时，先保留底层格式错误。
        return fmt.Errorf("打开 ZIP %s: %w", path, err)
    }
    defer zr.Close()

    for _, f := range zr.File {
        rc, err := f.Open()
        if err != nil {
            // 条目名能把“整个压缩包损坏”缩小为具体文件。
            if errors.Is(err, zip.ErrFormat) {
                return fmt.Errorf("条目 %s 的本地文件头无效: %w", f.Name, err)
            }
            return fmt.Errorf("打开条目 %s: %w", f.Name, err)
        }

        _, copyErr := io.Copy(io.Discard, rc)
        closeErr := rc.Close()
        if copyErr != nil {
            // 读到末尾才能触发部分压缩数据和 CRC 校验。
            if errors.Is(copyErr, zip.ErrChecksum) {
                return fmt.Errorf("条目 %s 的 CRC 校验失败: %w", f.Name, copyErr)
            }
            return fmt.Errorf("读取条目 %s: %w", f.Name, copyErr)
        }
        if closeErr != nil {
            // 关闭错误也要保留，避免吞掉底层读取异常。
            return fmt.Errorf("关闭条目 %s: %w", f.Name, closeErr)
        }
    }
    return nil
}

这里的判断重点不是把错误字符串写死，而是用 errors.Is 识别标准库错误。ErrFormat 更接近结构头、偏移或字段不一致；ErrChecksum 则说明数据已经读到校验边界，内容与头部记录的 CRC32 不一致。若遇到 ErrAlgorithm，问题是压缩方法没有对应解压器，不应当继续按“文件损坏”处理。

生成 ZIP 时把收尾动作做完整

如果问题发生在自己生成的归档，优先检查写入端。zip.NewWriter 写入的是条目数据，中央目录和归档结束记录要在 Writer.Close 时完成；输出文件即使已经有内容，漏掉这一步仍可能让下游读到不完整的归档。

out, err := os.Create("report.zip")
if err != nil {
    // 创建失败时不要继续持有一个无效输出句柄。
    return err
}
defer out.Close()

zw := zip.NewWriter(out)
w, err := zw.Create("report.txt")
if err != nil {
    // 创建条目失败时仍由调用方统一处理收尾。
    return err
}
if _, err := io.WriteString(w, "示例内容\n"); err != nil {
    // 条目写入错误通常意味着输出文件不能直接发布。
    return err
}
if err := zw.Close(); err != nil {
    // Close 会写入中央目录，必须检查其返回值。
    return err
}
return out.Close()

示例中的 os、io 导入略去只是为了突出收尾顺序；实际代码还要避免对同一个文件重复关闭后忽略错误。若归档经过对象存储、HTTP 上传或临时文件替换，再检查字节数、截断策略和最终文件是否来自完整写入，往往能找到“本机刚生成没事，传到另一台机器就损坏”的原因。

常见问题

只读取 Reader.File 数量，能证明 ZIP 完整吗？

不能。它主要证明目录条目已经被解析；要检查条目本身，还应调用 File.Open 并读到末尾。

DataOffset 适合拿来修复损坏文件吗？

不适合。它可以帮助定位数据偏移并验证本地头，但返回错误时应回到原始文件或生成链路修复，不要手工改偏移绕过检查。

为什么生成代码没有报错，读出来却是损坏头？

最常见原因是没有检查 Writer.Close，或者关闭前就上传、改名、复制了输出文件。把归档关闭成功作为发布前条件，再进行传输。