Go gzip 读取 checksum error 怎样区分内容损坏

gzip 文件能读出文字，却在结尾报 checksum error，不能据此把前面那段内容当成成功结果。本文制作一个只检查本地文件、不落地解压正文的小工具：保留完整错误链，区分不匹配、不完整和其他失败，再决定业务是否接收内容。

官方软件地址：https://go.dev/。示例使用标准库及 Go 1.16 起提供的 io.Discard，不依赖第三方包。以下代码与命令供读者本地执行，本文不把示意输出当作实测记录。

先明确工具目标：判断流完整性，不猜损坏来源

工具回答的是“这份输入能否被完整解码并通过 gzip 自带检查”，而不是“哪个系统弄坏了文件”。校验失败可能关联正文变化，也可能关联尾部记录不正确；只有错误类别，没有发送端原件、存储记录和传输链路证据，就不能定位责任环节。CRC 也不是防恶意修改的认证机制。

组成上，gzip 成员包含头部、压缩内容和尾部。尾部含 CRC32 与明文长度记录；读取器维护实际摘要和长度。源码在成员末尾比较记录值与计算值，两者任一不符都返回 ErrChecksum。因此日志中的“校验错误”不应被缩写成“CRC 一定错误”。

准备文件和项目目录

准备一个独立目录，将第三节完整代码保存为 main.go，再把需要检查的文件路径作为参数传入。请检查文件确实是 gzip 格式，而不是仅把扩展名改成 .gz 的普通文本、ZIP 或其他压缩格式。命令只针对你持有且允许处理的文件，不覆盖原文件。

# 在新建的独立示例目录初始化模块
go mod init example.com/gzipcheck
# 保存下方代码为 main.go 后检查自己的文件
go run . ./sample.gz

核心代码：完整读取并保留错误类别

check 使用 io.Copy 把明文写给丢弃接收器；它不保存明文，但仍读取整个输入。正常读到 EOF 时，io.Copy 返回的错误为 nil；真正的读取错误则原样沿错误链保留。先保存 readErr，再处理 closeErr，避免关闭结果掩盖解压失败。这里的字节数只是已消费的明文量，不是“已经验证成功”的长度。

package main

import (
    "compress/gzip"
    "errors"
    "fmt"
    "io"
    "os"
)

// classify 保留错误类型，不依赖英文报错字符串。
func classify(err error) string {
    switch {
    case errors.Is(err, gzip.ErrChecksum):
        return "校验或长度不匹配"
    case errors.Is(err, io.ErrUnexpectedEOF):
        return "压缩流不完整"
    case errors.Is(err, gzip.ErrHeader):
        return "gzip头不合法"
    case errors.Is(err, io.EOF):
        return "没有可读取的gzip成员"
    default:
        return "其他读取或解压错误"
    }
}

// check 只消费数据，不把尚未确认的内容提交给业务。
func check(path string) (int64, error) {
    f, err := os.Open(path)
    if err != nil {
        return 0, fmt.Errorf("打开文件: %w", err)
    }
    defer f.Close() // 关闭底层文件，与关闭gzip读取器分别负责。
    zr, err := gzip.NewReader(f)
    if err != nil {
        return 0, fmt.Errorf("初始化gzip: %w", err)
    }
    n, readErr := io.Copy(io.Discard, zr) // 不截断读取，也不在内存中保存全部明文。
    closeErr := zr.Close()
    if readErr != nil {
        return n, fmt.Errorf("读取gzip: %w", readErr)
    }
    if closeErr != nil {
        return n, fmt.Errorf("关闭gzip: %w", closeErr)
    }
    return n, nil
}

func main() {
    if len(os.Args) != 2 {
        fmt.Fprintln(os.Stderr, "用法: go run . 文件.gz")
        os.Exit(2)
    }
    n, err := check(os.Args[1])
    if err != nil {
        fmt.Fprintf(os.Stderr, "未通过；已读明文字节=%d；类别=%s；错误=%v\n",
            n, classify(err), err)
        os.Exit(1)
    }
    fmt.Printf("完整读取通过；明文字节=%d\n", n)
}

空输入在初始化时可能表现为 EOF，不能把它与完成解压后的 EOF 混成同一个成功分支。有效的空内容 gzip 文件则仍有格式结构，可以完整读完且明文字节为零。一个 Read 也可能同时返回字节和错误，所以“最后一批字节拿到了”仍不是通过信号。

本地使用：怎样解释成功与失败

成功提示仅表示本工具在默认多成员模式下完整读取结束，且没有获得读取或关闭错误。它不判断解压出的业务内容是否符合 JSON、CSV 等上层格式，更不证明内容来源可信。

出现“校验或长度不匹配”，说明获得了 ErrChecksum，应拒绝提交当前解压结果。出现“不完整”，说明当前读取所需的数据没有完整提供；常见排查方向包括文件被截断、上游未完整写出，但仅凭此错误不能确认是哪一种。错误阶段和原始错误都保留在日志里，方便与生产端记录对照。

“gzip头不合法”指格式入口问题或头部检查问题。若报其他错误，不要一律改名为 checksum：压缩数据本身可能触发 flate 错误，底层文件读取也可能失败。代码用 errors.Is 而非字符串包含判断；包装错误用 %w，使上层仍可分类。

接入业务：隔离未通过校验的内容

检查工具把数据交给 io.Discard，因此没有半成品业务文件。实际导入服务需要正文时，应把“暂存内容”与“已提交内容”分开：临时文件或可回滚区域只能被本次任务使用；完整消费无错误之后，才允许后续解析和提交。失败时，暂存内容按既定保留或清理策略处理，不应混入正式目录。

把 io.Discard 替换成文件写入器后，io.Copy 的错误也可能来自写入端，例如磁盘空间不足，不能全部归为压缩流损坏。还要单独处理输出文件关闭错误，以及业务所需的持久化与提交保证。检查成功和业务提交成功是两个条件，不要共用一个布尔值表示。

避免直接对解压流做不可撤销操作，例如逐行发通知或直接累加正式账户数据。因为尾部失败可能发生在已消费大量明文以后；若业务必须流式处理，需要事务或补偿设计，而不是发现错误后只打印一条警告。

验收边界：Close、拼接成员与资源限制

验收这段设计时，首先看完整读取是否保留错误，而非看 defer 是否写齐。Reader.Close 负责释放读取器资源，不会代替消费到末尾，也不会关闭底层文件。生产端则不同：Writer.Close 负责结束压缩写出，漏掉它可能造成不完整输出，不能把两个 Close 的作用类比。

其次看覆盖范围。默认 Multistream 为 true，拼接的 gzip 成员会作为连续内容读取；后续成员失败，也不能宣称整个输入通过。如果改为 Multistream(false)，一个成员结束不等于整个文件已经检查完，必须按容器协议处理剩余内容。不要为隐藏末尾异常而关闭多成员支持。

最后看资源预算。io.Discard 避免保存全部明文，但不能消除解压所需 CPU 和时间。服务端需要压缩输入大小、解压输出上限和任务时限；达到限制就应返回“超限或未完成”，不能把 LimitReader 自己制造的结束当作 gzip 已验证。校验通过只代表格式完整性条件满足，业务格式、来源认证和资源控制仍各有边界。

参考：Go gzip.Reader 官方文档；gzip 读取与尾部比较源码。错误含义依据官方接口与源码，责任来源的判断需要额外证据。