Go compress/gzip 出错时怎么排查流关闭

Go 的 compress/gzip 出错时，先不要只盯着 gzip.NewWriter 或 gzip.NewReader。写入方向要按“先关压缩层，再关底层输出”的顺序处理，并分别保留 Write、gzip.Writer.Close 与底层 Close 的错误；读取方向则必须持续读到 io.EOF，否则 GZIP 尾部校验可能还没有发生。

最常见的根因是把 gzip 流当成普通包装器：忽略 Writer.Close、提前停止读取，或用一个 defer 覆盖了前面真正有价值的错误。把每层错误加上前缀，通常几分钟就能判断是压缩器、底层文件还是输入数据出了问题。

先看关闭顺序：压缩写入要由内向外收口

gzip.NewWriter 只建立压缩层，真正的压缩字节可能仍在内存缓冲中。关闭它时，标准库会刷新未写数据并写入 GZIP footer；这个 footer 包含解压端判断完整性的必要信息。它不会关闭底层文件、网络连接或自定义 writer，所以两层都要明确处理。

写入时为什么要分别检查 Write 和 Close

只检查 io.Copy 的返回值不够，因为它只能覆盖复制过程中已经暴露的错误。最后的尾部写入通常发生在 gzip.Writer.Close，而文件系统或网络输出也可能在底层关闭时才报告错误。可以让函数返回命名错误，并按层级保留最先出现的错误：

func compressFile(dstPath string, src io.Reader) (err error) {
	// 先打开最终输出；底层文件的关闭错误也要保留。
	dst, err := os.Create(dstPath)
	if err != nil {
		return fmt.Errorf("创建输出文件: %w", err)
	}

	zw := gzip.NewWriter(dst)
	// 复制阶段的错误来自源 reader 或底层 writer。
	if _, err = io.Copy(zw, src); err != nil {
		_ = zw.Close()
		_ = dst.Close()
		return fmt.Errorf("写入 gzip 数据: %w", err)
	}
	// Close 会刷出缓冲并写入 GZIP footer，不能忽略返回值。
	if err = zw.Close(); err != nil {
		_ = dst.Close()
		return fmt.Errorf("关闭 gzip 流: %w", err)
	}
	// 压缩层完成后再关闭底层文件，错误边界更清楚。
	if err = dst.Close(); err != nil {
		return fmt.Errorf("关闭输出文件: %w", err)
	}
	return nil
}

实际项目中如果使用 Flush 做流式传输，也要检查它的返回值；Flush 只负责把当前压缩数据推到底层，不等于完整关闭，也不会替代最后一次 Close。

读取时如何把校验错误逼到 EOF

读取端的典型误区是拿到前几个字节就返回，或者只调用 Reader.Close 就认为输入完整。GZIP checksum 要在读到尾部时验证，因此排查损坏文件时应让读取动作走完，并分别记录解压层和底层输入层的错误：

func decompress(srcPath string, dst io.Writer) (err error) {
	src, err := os.Open(srcPath)
	if err != nil {
		return fmt.Errorf("打开 gzip 文件: %w", err)
	}
	defer func() {
		// 文件关闭只负责底层资源，不替代 gzip.Reader 的完整读取。
		if closeErr := src.Close(); err == nil && closeErr != nil {
			err = fmt.Errorf("关闭输入文件: %w", closeErr)
		}
	}()

	zr, err := gzip.NewReader(src)
	if err != nil {
		return fmt.Errorf("读取 gzip 头: %w", err)
	}
	if _, err = io.Copy(dst, zr); err != nil {
		_ = zr.Close()
		return fmt.Errorf("解压并读取到结尾: %w", err)
	}
	// 读到 EOF 后再关闭，保留 gzip 层的收尾错误。
	if err = zr.Close(); err != nil {
		return fmt.Errorf("关闭 gzip 读取器: %w", err)
	}
	return nil
}

这里的 io.Copy 不是为了追求吞吐数字，而是为了让 reader 消费到结尾。若错误前缀是“读取 gzip 头”，通常是头部格式或输入来源问题；若前缀落在“解压并读取到结尾”，则应优先检查截断、拼接和传输完整性。

用最小复现定位是哪一层关闭失败

当线上错误只写着“gzip 失败”，可以把底层 writer 换成一个会在指定写入次数后返回错误的测试 double，再把每个边界包上固定前缀。重点不是模拟真实磁盘，而是验证错误究竟出现在复制、压缩层收尾还是底层关闭。

type namedWriter struct {
	w io.Writer
}

func (n namedWriter) Write(p []byte) (int, error) {
	// 为底层错误增加稳定前缀，便于日志检索和单元测试断言。
	count, err := n.w.Write(p)
	if err != nil {
		return count, fmt.Errorf("底层输出: %w", err)
	}
	return count, nil
}

不要用“再调用一次 Close”来修复同一个失败：关闭后的对象通常不会产生新的有效信息。先确认哪一层返回错误，再决定是处理短写、替换输出目标、保证输入读到 EOF，还是修正资源的关闭顺序。

相关问题

为什么生成的 gzip 文件能打开，却偶尔校验失败？ 常见原因是写完后没有成功执行 gzip.Writer.Close，导致尾部不完整；也可能是传输或存储过程截断。

gzip.Reader.Close 会关闭文件吗？ 不会。它只结束 gzip 读取器，底层文件仍由调用方关闭。

什么时候需要调用 Flush？ 只有在压缩数据要分段发送、接收端需要及时看到当前片段时才考虑；文件归档场景仍要以最终 Close 完成尾部写入。

排查时可以按一张清单收尾：写入是否检查了 Write；gzip.Writer.Close 是否成功；底层输出是否关闭；读取是否真正到达 io.EOF；日志是否保留了每层错误前缀。五项都明确后，流关闭问题通常就能从“gzip 不稳定”收敛到一个可修复的边界。