compress/zlib NewReader 遇到校验错误怎么识别

compress/zlib.NewReader 遇到校验错误时，不要只检查创建读取器这一步。正确做法是：先处理 NewReader 的初始化错误，再把返回的读取器完整读到 io.EOF，最后用 errors.Is(err, zlib.ErrChecksum) 判断校验失败。因为 zlib 的校验尾部要在解压数据读完后才会被消费。

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

这篇只讨论校验错误、读取错误和关闭顺序，不涉及密码保护或预置字典。下面用一个小型命令行工具把错误出现的阶段分开。

为什么 NewReader 成功不代表数据已经通过校验

zlib.NewReader 返回的是一个 io.ReadCloser。它首先检查 zlib 头部，并准备解压器；真正读取数据时，解压内容经过底层 flate 解码，直到末尾才读取 zlib 尾部的 Adler-32 校验值。也就是说，输入内容即使尾部校验不匹配，NewReader 也可能先返回 nil 错误。

官方实现明确把校验放在读到解压器的 io.EOF 之后。如果尾部只有一部分字节，会得到读取错误；如果四字节校验值存在但不匹配，才会返回 zlib.ErrChecksum。因此只读前几 KB、拿到一部分明文就提前结束，不能说明整个压缩流有效。

先把初始化错误和读取错误分开

第一层判断只负责确认“读取器能否建立”。例如头部不是合法 zlib 数据时，错误会在 NewReader 处返回；此时没有可关闭的读取器。创建成功后要立即注册 defer zr.Close()，并把后续的完整消费交给 io.Copy 或循环读取。

package main

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

func decodeFile(path string) error {
	// 输入文件只负责提供压缩字节，打开失败不能归类为 zlib 校验错误。
	f, err := os.Open(path)
	if err != nil {
		return fmt.Errorf("打开压缩文件: %w", err)
	}
	defer f.Close()

	// NewReader 主要检查 zlib 头部并创建解压读取器。
	zr, err := zlib.NewReader(f)
	if err != nil {
		return fmt.Errorf("创建 zlib 读取器: %w", err)
	}
	defer zr.Close()

	// 必须持续读取到末尾，尾部校验才有机会被检查。
	_, err = io.Copy(io.Discard, zr)
	if err != nil {
		return fmt.Errorf("读取 zlib 数据: %w", err)
	}
	return nil
}

func main() {
	// 示例入口只展示错误分层，实际项目可把路径改成命令行参数。
	if err := decodeFile("payload.zlib"); err != nil {
		fmt.Println(err)
	}
}

var _ = errors.Is // 后文使用 errors.Is 识别 zlib.ErrChecksum。

示例中的 io.Discard 只是为了完整消费并触发校验，不代表业务一定要丢弃明文。实际项目可以换成文件、哈希计算器或业务解析器，但必须继续处理读取返回的错误。

用 errors.Is 识别 ErrChecksum

zlib.ErrChecksum 是标准库提供的哨兵错误，含义是“读取 zlib 数据时校验和无效”。如果上层对错误做了 fmt.Errorf("...: %w", err) 包装，使用 errors.Is 仍然可以识别它，不要依赖错误字符串比较。

func classifyDecodeError(err error) error {
	if err == nil {
		return nil
	}
	if errors.Is(err, zlib.ErrChecksum) {
		// 校验尾部存在，但它与已解压内容计算出的值不一致。
		return fmt.Errorf("压缩数据校验失败，请检查传输或生成端: %w", err)
	}
	if errors.Is(err, io.ErrUnexpectedEOF) {
		// 输入在读取完整尾部前结束，优先排查截断或未写完的文件。
		return fmt.Errorf("压缩数据不完整: %w", err)
	}
	// 这里保留 flate 解码错误、磁盘读取错误等其他原因。
	return fmt.Errorf("读取压缩流失败: %w", err)
}

func decodeAndClassify(path string) error {
	f, err := os.Open(path)
	if err != nil {
		return err
	}
	defer f.Close()

	zr, err := zlib.NewReader(f)
	if err != nil {
		// 头部错误发生在读取器创建阶段，不会走到 defer zr.Close。
		return fmt.Errorf("zlib 头部无效: %w", err)
	}
	defer zr.Close()

	_, err = io.Copy(io.Discard, zr)
	return classifyDecodeError(err)
}

这里有三个容易混淆的边界：NewReader 返回错误通常是头部或字典问题；io.Copy 返回的 zlib.ErrChecksum 表示尾部校验不匹配；io.ErrUnexpectedEOF 则更像输入被截断。底层压缩数据损坏也可能返回其他解压错误，不能把所有非 nil 错误都标成校验失败。

把完整消费和 Close 放在固定位置

调用 Close 不会替代完整读取。官方文档说明，只有读取到 io.EOF，zlib 校验才会被验证；Close 主要负责结束解压器本身，而且不会关闭传给 NewReader 的底层 io.Reader。因此文件和 zlib 读取器要分别关闭。

工程上可以固定下面的顺序：打开底层输入，创建 zlib 读取器，立刻注册读取器的 defer Close，完整消费，按哨兵错误分类，最后由外层关闭文件。若只做预览，只能说“已读出一部分明文”，不能把它当作“压缩包已通过完整性检查”。

相关问题

为什么 NewReader 返回 nil 错误，后面仍然失败？

创建读取器和验证完整压缩流是两个阶段。尾部校验要等解压内容读完后才会检查，所以失败可能出现在 Read、io.Copy 或循环读取的返回值中。

可以比较字符串“zlib: invalid checksum”吗？

不建议。使用 errors.Is(err, zlib.ErrChecksum)，这样即使错误被 %w 包装，分类逻辑也不会依赖具体文本。

只读取一部分内容后调用 Close 能发现校验错误吗？

不能把它当作完整校验。需要继续消费到 io.EOF；如果业务只需前缀，应明确记录这是部分读取，而不是完整性检查通过。