Go gzip Reader 为什么读取后校验失败

我第一次遇到这个错误时，解压出来的文本看起来完全正常，直到业务在读取结束时突然收到 gzip: invalid checksum。这不是 Go 把正常文本误判成错误，而是 gzip.Reader 直到读到流尾部，才有机会把已解压内容的校验值和 gzip 尾部记录的值比较。

处理这类问题的关键只有一句话：不要把“已经读到一些内容”当成成功，必须把 Reader 读到 io.EOF，再判断错误。官方参考：https://pkg.go.dev/compress/gzip

为什么内容正常，最后仍然会 ErrChecksum

gzip 成员的尾部保存了未压缩数据的 CRC-32 和长度。Go 的 Reader 会边读边解压，同时累计这两个值；当压缩成员结束时，才读取尾部并比较。只要实际字节被截断、传输途中改变，或者写入端没有正确完成收尾，最后一步就会返回 gzip.ErrChecksum。

NewReader 成功只代表头部可识别，不代表整个成员已经可信；中途 Read 返回的字节也只能视为暂定数据。

正确做法是把读取结果和错误一起收口

最稳妥的写法是让 io.ReadAll 或 io.Copy 负责持续读取，最后统一检查错误。不要只读一次，也不要只判断返回的字节数。

package main

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

func readGZIP(src io.Reader) ([]byte, error) {
    // NewReader 只解析 gzip 头部，完整性要等后续读到成员尾部才能判断。
    zr, err := gzip.NewReader(src)
    if err != nil {
        return nil, fmt.Errorf("create gzip reader: %w", err)
    }
    defer zr.Close() // Close 不关闭 src，且不代替读到 EOF。

    // ReadAll 会继续读取到 EOF，让 Reader 有机会校验 CRC-32 和长度。
    data, err := io.ReadAll(zr)
    if err != nil {
        if errors.Is(err, gzip.ErrChecksum) {
            return nil, fmt.Errorf("compressed data is damaged: %w", err)
        }
        if errors.Is(err, io.ErrUnexpectedEOF) {
            return nil, fmt.Errorf("compressed data is truncated: %w", err)
        }
        return nil, fmt.Errorf("read gzip data: %w", err)
    }
    return data, nil
}

这里的成功条件是 ReadAll 返回的错误为 nil，而不是“data 非空”。即使损坏发生在最后一个块，前面读出的内容也不能直接交给下游。

从错误类型反推输入链路

• ErrHeader：开头就不像合法 gzip，常见于把未压缩响应、错误页或错误格式交给了 gzip.Reader。
• io.ErrUnexpectedEOF：流在必要字节读完前就结束，更像是传输截断或文件未写完。
• ErrChecksum：已经读到成员尾部，但 CRC-32 或未压缩长度与尾部记录不一致，重点检查字节是否被修改，以及生成端是否正确结束。

如果压缩数据来自 HTTP 响应，还要确认中间层没有把 gzip 内容先解压再错误地保留原来的 Content-Encoding。如果来自文件，先检查文件是否在写入完成后才被读取。

写入端和多成员流的两个容易忽略点

gzip.Writer 会缓冲数据，必须调用 Close 才会写出尾部。仅调用 Write 后读取目标文件，可能得到一个看似有内容、实际没有完整 trailer 的文件。

var buf bytes.Buffer
zw := gzip.NewWriter(&buf)
// Write 只提交待压缩内容，尾部还没有保证写出。
if _, err := zw.Write(payload); err != nil {
    return err
}
// Close 刷新缓冲区并写入 gzip 尾部，必须检查它的错误。
if err := zw.Close(); err != nil {
    return err
}

另外，Reader 默认允许连续 gzip 成员拼接，并把它们看成一段解压结果。如果协议需要在第一个成员结束后停下，应显式调用 Multistream(false)，但这只改变成员边界处理，不会绕过校验。

排查时可以记住的结论

1. 先完整读取到 EOF，再把数据交给业务。
2. 优先检查输入是否截断、被改写，以及 Writer 是否 Close。
3. 用 errors.Is 判断 gzip.ErrChecksum，不要依赖错误字符串。

常见追问：调用 zr.Close() 能不能触发校验？不能，它不会替代完整读取。只读前几 KB 能不能确认文件没坏？不能，尾部校验尚未到达。多成员 gzip 报错怎么办？先确认每个成员都完整，再根据协议选择默认的多成员行为或 Multistream(false)。