Go gzip 读取结束为什么才返回 ErrChecksum

用 Go 的 compress/gzip 读文件时，前面几次 Read 都拿到了正文，偏偏读到末尾才出现 gzip: invalid checksum，这不是读取器“突然把正常数据改错了”。gzip 的长度和校验信息位于压缩流尾部，gzip.Reader 只有消费到结束位置，才能把已解压数据与尾部记录进行比对。因此，读取过程中得到的字节只能视为暂时结果；没有把读取循环推进到 io.EOF 或明确的错误，就不能宣布文件完整。

为什么前面能读，最后才报 ErrChecksum

gzip 文件不只包含 deflate 压缩块，还在每个成员的尾部保存未压缩数据的 CRC-32 和长度。Go 文档把 gzip.ErrChecksum 定义为无效校验和错误，并说明 Reader 读到未压缩数据末尾时才检查预期长度和校验值。也就是说，前面的返回值证明“这些字节可以被解压”，不证明“整个成员已经完整且可信”。

这也解释了一个常见误判：gzip.NewReader 成功，只代表头部格式能识别；它不会替应用提前读完整个文件。若文件最后几个字节被截掉、传输中间发生替换，或者写入端没有正确收尾，正文可能已经输出了一大段，尾部校验仍然会失败。

先把读取循环写成“完整消费后再判断”

排查时不要只读一小段就把缓冲区交给下游，也不要因为已经拿到业务需要的前 N 字节就忽略剩余输入。需要确认文件完整时，应继续读取直到 io.EOF，并把 ErrChecksum 与普通 I/O 错误区分开：

// readGZIP 完整消费 gzip 成员，避免只验证到中途就使用结果。
func readGZIP(src io.Reader) ([]byte, error) {
	zr, err := gzip.NewReader(src)
	if err != nil {
		// 这里通常是头部格式错误，不是尾部校验失败。
		return nil, fmt.Errorf("创建 gzip reader: %w", err)
	}
	defer zr.Close() // Close 不负责替代完整读取，也不关闭底层 src。

	data, err := io.ReadAll(zr) // ReadAll 会持续读取，直到 EOF 或遇到错误。
	if err != nil {
		if errors.Is(err, gzip.ErrChecksum) {
			// 到达尾部后才发现 CRC 或长度字段不匹配。
			return nil, fmt.Errorf("gzip 尾部校验失败: %w", err)
		}
		return nil, fmt.Errorf("读取 gzip 数据失败: %w", err)
	}
	return data, nil // 只有正常 EOF 才把 data 当成完整内容。
}

这里没有用“读到部分数据就返回”的方式掩盖错误。若业务必须流式处理，可以边读边消费，但要把已消费的数据标记为待确认；最终收到校验错误时，应丢弃本次对象、回滚临时文件或重新拉取，而不是把不完整结果写成正式文件。

按输入链路定位真正损坏的位置

同一个错误往往不是 gzip 算法本身的问题。先检查源文件大小和传输层的 Content-Length、分块结束状态，再确认接收端没有把压缩字节转成字符串或经过错误的文本处理。对文件流，截断通常表现为正文读到某个位置后才失败；对 HTTP 流，代理或上游提前关闭连接也会留下相同症状。

如果压缩数据由 Go 生成，最容易漏的是 Writer.Close。Write 只提交输入，gzip 的尾部记录要在关闭时写出；只关闭底层文件而不关闭 gzip writer，接收端就可能拿到一个看似有内容、实际没有完整 trailer 的成员。

// writeGZIP 先结束 gzip writer，再关闭真正的目标文件。
func writeGZIP(dst io.WriteCloser, src io.Reader) error {
	zw := gzip.NewWriter(dst)
	if _, err := io.Copy(zw, src); err != nil {
		// 输入读取失败时仍尝试关闭 writer，避免遗漏内部状态。
		_ = zw.Close()
		_ = dst.Close()
		return fmt.Errorf("压缩输入失败: %w", err)
	}
	if err := zw.Close(); err != nil {
		// Close 会刷新缓冲并写入 gzip footer，必须检查它的错误。
		_ = dst.Close()
		return fmt.Errorf("写入 gzip 尾部失败: %w", err)
	}
	return dst.Close() // gzip 已收尾后，最后才关闭底层目标。
}

多成员 gzip 默认会被 Reader 连续读取。如果文件格式要求只处理一个成员，可调用 Multistream(false)，在单个成员结束处停止，再由调用方决定如何处理后面的字节。但这个开关不能修复已经损坏的 CRC；它只改变成员边界的读取策略。

修复后用四项清单复查

常见问题

调用 zr.Close() 能不能触发校验？

不能把它当作完整校验入口。官方文档要求先把 Reader 消费到 io.EOF，Close 本身也不会关闭底层 reader。

已经读到的正文还能不能继续使用？

只有在应用允许“尽力读取”的场景才可以保留作诊断。完整文件、配置、归档和消息体应把校验错误视为失败，丢弃或重新获取。

为什么改成 io.Copy 后问题消失？

通常不是 io.Copy 修复了压缩数据，而是它自然地把输入读到结束，让尾部校验真正执行；如果源数据本来损坏，io.Copy 仍会返回错误。

因此，Go gzip 读取结束时才返回 ErrChecksum 是设计上的完整性检查时机。把读取推进到结束、区分头部错误和尾部错误，并确保写入端先关闭 gzip writer，通常就能把“最后才报错”的现象定位到具体链路。