Go gzip 为什么解压出现校验错误

Go gzip 解压出现 gzip: invalid checksum，通常不是“压缩算法不兼容”，而是解压后的字节内容与 gzip 尾部记录的 CRC32 或原始长度对不上。最常见的根因是写入端没有调用 Writer.Close、文件或响应体被截断，或者读取端还没有真正读到 io.EOF 就开始判断结果。

官方文档：https://pkg.go.dev/compress/gzip

先把错误定位为“数据尾部校验不匹配”，再沿着“压缩端收尾—传输完整性—读取到 EOF—多成员流”四个边界排查。Reader.Close 不会替代完整读取，也不会修复已经损坏的 gzip 数据。

ErrChecksum 到底在检查什么

gzip 数据流的尾部包含未压缩数据的 CRC32 和长度信息。Go 的 gzip.Reader 会在接近未压缩数据末尾时检查这些字段；如果校验值或长度不匹配，就返回 gzip.ErrChecksum。因此，前面已经读出的内容只能视为暂时结果，收到 io.EOF 之前不能把它当成完整文件。

这也解释了一个容易误判的现象：gzip.NewReader 成功，只能说明头部看起来像 gzip，不能证明整个压缩流完整。若头部本身损坏，通常更接近 gzip.ErrHeader；若尾部或内容被改动，才更可能落到 ErrChecksum。

先检查压缩端有没有完整收尾

如果问题发生在自己生成 gzip 的链路，第一检查点是 Writer.Close。Write 只是把数据交给压缩器，最终的尾部信息要在关闭时写入底层输出。忽略 Close 返回的错误，或者在关闭前就读取输出，都可能得到一个看似有内容、实际缺尾部的文件。

package main

import (
    "bytes"
    "compress/gzip"
    "fmt"
)

func makeGZIP(input []byte) ([]byte, error) {
    var output bytes.Buffer
    writer := gzip.NewWriter(&output)

    // Write 只提交未压缩数据，gzip 尾部要等 Close 才会写入。
    if _, err := writer.Write(input); err != nil {
        return nil, fmt.Errorf("write gzip data: %w", err)
    }
    // Close 同时刷新压缩器并写入 CRC32、原始长度等尾部信息。
    if err := writer.Close(); err != nil {
        return nil, fmt.Errorf("close gzip writer: %w", err)
    }
    return output.Bytes(), nil
}

如果底层是文件，还要检查文件写入是否报错、是否在 Close 完成前被复制或上传。如果底层是 HTTP 响应，则不能把一次 Flush 当成 gzip 已完成；应用层仍需保证发送端正常结束。

读取端必须把流读到 EOF

校验发生在读取末尾，所以只读一小段、读取到目标字段就提前返回，或者只调用 Reader.Close，都可能错过校验。对完整文件，最直接的方式是让 io.Copy 读完并检查它的错误。

package main

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

func readGZIP(source io.Reader, destination io.Writer) error {
    reader, err := gzip.NewReader(source)
    if err != nil {
        return fmt.Errorf("create gzip reader: %w", err)
    }
    defer reader.Close()

    // Copy 会持续读取直到 EOF，gzip Reader 才有机会检查尾部校验。
    if _, err := io.Copy(destination, reader); err != nil {
        if errors.Is(err, gzip.ErrChecksum) {
            return fmt.Errorf("gzip data is incomplete or corrupted: %w", err)
        }
        return fmt.Errorf("read gzip stream: %w", err)
    }
    return nil
}

不要把“已经得到部分文本”当成成功。对于配置、备份或导入文件，最好先写入临时目标，等 io.Copy 成功后再替换正式文件；这样校验失败时不会留下半份结果。

文件没坏时，还要排查传输和多成员流

如果本地原始 gzip 能解压，而服务读取失败，优先比较传输前后的字节数和存储对象的完整性。常见问题包括只上传了前半段、代理按文本处理二进制、响应体被提前关闭，或把 gzip 响应再次按错误的方式拼接。不要先通过重试掩盖截断，因为每次拿到的内容可能仍然不完整。

gzip 允许多个成员流连续出现。Go 默认会把连续成员当成一个逻辑输入；如果协议需要在第一个 gzip 成员后读取别的格式，就应显式关闭多成员模式，并让底层 reader 支持按字节回退边界。

package main

import (
    "bufio"
    "compress/gzip"
    "io"
)

func readOneMember(source io.Reader, destination io.Writer) error {
    // ByteReader 让 gzip Reader 能停在当前成员结束的位置。
    buffered := bufio.NewReader(source)
    reader, err := gzip.NewReader(buffered)
    if err != nil {
        return err
    }
    defer reader.Close()

    // false 表示只处理一个成员，后续字节留给外层协议。
    reader.Multistream(false)
    _, err = io.Copy(destination, reader)
    return err
}

只有当数据协议确实区分成员流和后续数据时才使用 Multistream(false)。普通的 gzip 文件或连续 gzip 文件，保持默认行为更简单。若单成员模式仍出现校验错误，回到“当前成员是否完整”的问题，不要把 Multistream 当作修复损坏数据的开关。

按这张表快速缩小范围

排查顺序可以固定为：确认输入格式，确认压缩端收尾，确认传输没有截断，确认读取到 EOF，最后才判断是否需要单成员模式。这样能把“校验错误”从一个笼统报错还原成具体的数据边界问题。

相关问题

调用 Reader.Close 后为什么没有得到校验错误？

Reader.Close 只关闭解压器，不负责把底层输入读到末尾。要触发完整校验，应先把数据读到 io.EOF，再处理读取错误。

把 CRC32 校验关掉能解决问题吗？

Go 的 gzip Reader 不提供一个用于跳过完整性检查的常规开关。即使绕过检查，也只会隐藏截断或内容被改写，不能让缺失的字节恢复。

为什么解压出部分内容后才报错？

gzip 的尾部校验需要等解压数据读完才能比较，所以部分内容已经返回并不代表整个输入可信。导入类业务应只在完整读取成功后提交结果。

参考资料

Go gzip 包文档：https://pkg.go.dev/compress/gzip

Go 官方 gzip 实现：https://go.dev/src/compress/gzip/gunzip.go

GZIP 文件格式规范：https://www.ietf.org/rfc/rfc1952.pdf