Go gzip写入后不调用Close导致尾部校验缺失的定位方法

我在排查 Go 生成的 gzip 文件时遇到过一种很容易误判的情况：Write 返回了 nil，文件也确实有内容，但接收端在读到末尾时报校验错误，或者压缩流无法被完整识别。问题通常不在压缩级别，而是把“写入完成”误当成了“gzip 文件完成”。

对 compress/gzip.Writer 来说，Write 只代表数据交给了压缩层；结束时必须检查 Close。它会刷新剩余压缩数据并写入 GZIP footer，但不会替你关闭底层 io.Writer。

本文用一个小型压缩工具复现这个边界，并给出文件、网络流都适用的错误处理顺序。官方文档见 https://pkg.go.dev/compress/gzip。

先把 Write 成功和文件完成分开

gzip writer 内部可能暂存压缩数据。调用 Write 后，底层 writer 收到的字节不一定已经包含完整尾部；只有 Close 才会把未写出的数据刷下去，并写入用于长度和校验的 GZIP footer。因此排查时先看三件事：写入错误、压缩层关闭错误、底层资源关闭错误。

package main

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

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

    // Write 只负责把数据交给压缩层，不能代替收尾。
    if _, err := zw.Write(input); err != nil {
        return nil, fmt.Errorf("写入 gzip 数据: %w", err)
    }
    // Close 会刷新缓冲区并写入 footer；这个错误必须返回给调用方。
    if err := zw.Close(); err != nil {
        return nil, fmt.Errorf("关闭 gzip writer: %w", err)
    }
    return buf.Bytes(), nil
}

这里没有使用 defer zw.Close() 来掩盖错误：如果 Close 失败，函数必须把失败状态带回去。对于只写内存缓冲的例子，底层没有独立的关闭动作；换成文件或网络流后仍要沿用这个检查。

关闭顺序要先压缩层，再底层 writer

当底层是文件、管道或请求体时，关闭顺序不能反过来。先关闭底层 writer 可能让 gzip 的最后一次写出失败；正确顺序是先 zw.Close()，再关闭底层对象，并分别记录错误。若两个动作都失败，通常优先返回 gzip 收尾错误，同时保留底层错误用于日志。

func writeGZIPFile(path string, input []byte) (err error) {
    f, err := os.Create(path)
    if err != nil {
        return fmt.Errorf("创建文件: %w", err)
    }
    // 底层文件的关闭错误不能被忽略，作为没有提前返回时的兜底结果。
    defer func() {
        if closeErr := f.Close(); err == nil && closeErr != nil {
            err = fmt.Errorf("关闭文件: %w", closeErr)
        }
    }()

    zw := gzip.NewWriter(f)
    // defer 只负责兜底记录，主流程仍要显式检查 gzip Close。
    if _, err = zw.Write(input); err != nil {
        return fmt.Errorf("写入压缩层: %w", err)
    }
    if err = zw.Close(); err != nil {
        return fmt.Errorf("完成 gzip 尾部: %w", err)
    }
    return nil
}

上面的函数需要补充 os 导入。关键点是不要在 defer 中悄悄调用并丢弃 zw.Close 的返回值；命名返回值只适合承接底层文件的最后关闭错误，压缩层仍在主路径完成。

如果底层是 HTTP 请求体或 io.PipeWriter，还要按照协议决定谁负责关闭底层对象。gzip 的 Close 只关闭压缩层，不会替调用方关闭底层 writer。

用读取到 EOF 证明尾部校验真的完成

生成端没有报错，还不等于接收端已经验证完整。读取 gzip 时，应该持续读到 io.EOF，再把读取错误作为证据；不能只读到一部分内容就认为成功。

func verifyGZIP(data []byte) error {
    zr, err := gzip.NewReader(bytes.NewReader(data))
    if err != nil {
        return fmt.Errorf("创建 gzip reader: %w", err)
    }
    // Reader.Close 不会替代读到 EOF，完整读取才会触发长度和 checksum 检查。
    defer zr.Close()
    if _, err := io.Copy(io.Discard, zr); err != nil {
        return fmt.Errorf("读取并校验 gzip: %w", err)
    }
    return nil
}

这里的 io.Copy 会把流读到结束。若 footer 缺失或内容被截断，常见证据会出现在读取阶段，例如 checksum 或 unexpected EOF。定位时可以把生成端的 Close 结果和消费端的读取错误放在同一条日志里，不要只记录“Write 成功”。

常见误区与排查清单

• 把 Write 返回 nil 当作 gzip 文件已经完整：确认是否检查了 zw.Close。
• 先关闭文件或管道，再关闭 gzip writer：调整为先压缩层、后底层资源。
• 只检查 Reader.Close：先持续读取到 io.EOF，再处理读取错误。
• 关闭错误被 defer 吞掉：让主流程返回压缩层错误，底层关闭错误至少进入日志。

可以把最终契约记成一句话：写入检查 Write，收尾检查 gzip Close，读取检查读到 EOF，资源再按所有权关闭。这样无论底层是 bytes.Buffer、文件还是网络管道，尾部校验缺失都能从责任边界开始定位。

相关问题

为什么调用 Flush 还不够？ Flush 只把当前压缩数据刷到底层，不能替代 Close 写入最终 footer；完整文件仍需要 Close。

gzip.Writer.Close 会关闭文件吗？ 不会。它只关闭 gzip 层，底层文件、管道或请求体仍由创建它们的代码负责。