Go 压缩归档 gzip Close 缺失为何损坏

Go gzip 文件缺少 Writer.Close，可能没有完整写出压缩数据与 GZIP 尾部，因此解压器会把它当作未完成的流。io.Copy 或 Write 返回成功，只说明该次写入没有报告错误，不代表整个 gzip 文件已经结束。正确收尾是先关闭 gzip.Writer，再关闭它依赖的文件，并处理两者返回的错误。

官方文档地址：https://pkg.go.dev/compress/gzip。本文只讨论单个 gzip 数据流的生成与交付；gzip 本身不是多个文件的目录归档容器，tar.gz 还多一层 tar 收尾责任。

生产目标：完成压缩流后才交付文件

生产导出任务的目标应是“只有完整生成的文件才能交给后续环节”，而不是“目录里出现一个 .gz 文件就算成功”。文件可以在压缩刚开始时已经存在；文件大小持续增加，也不意味着尾部已经写好。

缺少 Close 时，有的解压器仍能读出部分甚至看似全部正文，随后在读到末尾时失败。不能据此前面有内容就认定文件正常，也不能把所有末尾错误都归因于 Close 缺失；传输截断、磁盘写入错误同样需要排查。

环境准备：明确两层 Writer 的职责

示例只依赖标准库，使用 errors.Join，需要 Go 1.20 或更高版本。将后面的代码保存为 main.go。压缩器 zw 负责 gzip 编码，file 负责文件描述符；zw.Close 不会代替 file.Close，反过来 file.Close 也不会帮压缩器补写尾部。

收尾配置：显式保留每个阶段的错误

package main

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

// stage 保留阶段名称与原始错误，供调用方记录和判断。
func stage(name string, err error) error {
    if err == nil {
        return nil
    }
    return fmt.Errorf("%s: %w", name, err)
}

// BuildGzip 创建独立暂存文件；仅全部写入及关闭成功才返回路径。
// dir 必须由服务配置提供；src 的关闭责任仍属于调用方。
func BuildGzip(dir string, src io.Reader) (string, error) {
    file, err := os.CreateTemp(dir, "export-*.gz")
    if err != nil {
        return "", stage("创建暂存文件", err)
    }
    path := file.Name()
    zw := gzip.NewWriter(file)

    _, copyErr := io.Copy(zw, src)
    // 即使复制失败，也尝试结束压缩器，再关闭底层文件。
    gzipErr := zw.Close()
    fileErr := file.Close()
    buildErr := errors.Join(
        stage("复制源数据", copyErr),
        stage("gzip收尾", gzipErr),
        stage("关闭文件", fileErr),
    )
    if buildErr != nil {
        // 删除失败也要报告，便于清理遗留文件；绝不返回交付路径。
        removeErr := os.Remove(path)
        return "", errors.Join(buildErr, stage("删除失败产物", removeErr))
    }
    return path, nil
}

func main() {
    // 当前目录仅用于本地演示；服务端应改用独立的受控暂存目录。
    path, err := BuildGzip(".", strings.NewReader("item,quantity\nbox,3\n"))
    if err != nil {
        fmt.Println("导出失败:", err)
        return
    }
    // 此时只代表生成阶段成功，尚未执行下载、上传或改名发布。
    fmt.Println("生成完成:", path)
}

关闭顺序直接写在函数体中，便于看清 gzip 在文件仍可写时完成收尾。复制源数据失败后仍尝试 Close，是为了清理本函数拥有的资源；但即使此时 gzip 收尾成功，源数据仍不完整，所以该任务必须失败。

errors.Join 同时保留复制、压缩收尾、文件关闭的错误。stage 对 nil 原样返回 nil，避免把成功阶段包装成非空错误。调用方只在 err 为 nil 时得到路径，便于把生成完成与交付动作分开。

使用 defer 本身没有问题，问题是忽略错误或在外层 defer 执行前就开始交付。例如同一函数中先 defer zw.Close，再上传尚未收尾的文件，上传发生时流仍可能未完成。把生成封装进独立函数后，只有它完成收尾并返回，调用方才继续处理。

权限边界：临时文件不等于已发布产物

CreateTemp 生成独立文件名，避免示例直接覆盖已有成品。目录应由服务配置选择，不直接采用外部请求中的任意路径。临时文件默认采用较收敛的权限创建，但目录访问策略和进程权限仍需由部署环境负责。

临时文件从创建时就在文件系统里存在。若把暂存目录直接暴露给下载服务，其他请求仍可能读到未完成内容，所以不能只依赖函数尚未返回路径。应将暂存区与对外下载目录分开，生成成功后再执行应用的发布动作。

失败后删除也可能失败，示例会把这项错误一并返回。服务需要用任务标识记录遗留文件并安排清理。成功生成的暂存文件则转交调用方管理，不能在函数末尾无条件删除。

日志记录：区分源数据失败与流损坏

日志应记录任务标识、失败阶段和可公开的错误分类，避免把整个导出内容写进日志。内层 Copy 失败与 Close 失败可能同时发生，不能为了只显示一个错误而覆盖原始原因。

可以按以下线索定位：源读取报错时先追查数据来源；gzip 收尾报错时查看底层输出失败；文件关闭报错时确认存储环境；上传后才出现截断时比较生成与传输环节。阶段日志用于缩小范围，不代表只凭一条日志就能证明根因。

若还叠加 bufio.Writer，则 gzip.Close 后还要刷新这层缓冲，再关闭文件。若还叠加 tar.Writer，则 tar 也必须在 gzip 结束前完成。应按依赖结构逐层明确责任，不能把本文双层代码照搬为任何 Writer 组合的通用清理器。

交付检查：不要只看文件能否打开

读者运行示例后，会在当前目录得到一个独立暂存文件。下面命令供自行复现；本文没有执行示例、展示实际解压输出或声称做过性能测试。

# 在保存 main.go 的目录运行，记录程序返回的产物路径
go run main.go

交付逻辑必须先检查生成函数的错误，再处理改名、上传或下载。网络写入全部完成与对象存储上传成功也各有自己的错误回执，gzip.Close 不能替代这些确认。需要断电恢复保证时，还要按目标文件系统和部署方式设计同步与提交策略，不能把 Close 成功直接称为持久化完成。

空数据也需要 gzip.Close 吗？

需要。空正文仍应构成完整 gzip 流，不能因为没有调用 Write 就省略格式收尾。

gzip Reader.Close 能发现所有损坏吗？

不能。读取端要消费到流末尾并处理读取错误，才能完成 gzip 的长度与校验信息检查；提前停止后调用 Reader.Close 不会替你读完，也不关闭底层输入。

直接 Reset 换输出文件能补完上一份吗？

不能把 Reset 当成上一份流的成功收尾。复用压缩器之前，应先按上一份任务的成功或失败路径完成资源处理。

事实依据：gzip Writer.Close 与 Flush 官方说明、errors.Join 官方说明、os.CreateTemp 官方说明。代码与交付契约为本文独立组织。