Go gzip Header 的文件名与注释字段设置

用 Go 生成 gzip 文件时，如果希望解压工具显示一个文件名或备注，不需要把这些信息拼进压缩正文，而是设置 compress/gzip 的 Header 字段：Name 表示原始文件名，Comment 表示注释。关键顺序是：在 Write、Flush 或 Close 第一次触发头部写入之前完成设置。

这两个字段是可选的 gzip 元数据，不会改变正文的字节内容。还要特别注意，Go 文档规定 Header 字符串必须是 UTF-8，并且只能包含 U+0001 到 U+00FF 范围内的 Unicode 码点，所以中文文件名或中文注释不能直接当作 Header 值写入。

先区分 Name 和 Comment 的职责

Name 是压缩数据对应的原始文件名，通常写成带扩展名的短名称；Comment 是给阅读者或工具看的说明文字。两者都在 gzip 文件头中，和后面的压缩正文处于不同层次。

因此，下面这种写法表达的是“给 gzip 文件补充元数据”，而不是在正文开头额外写入两行文本：

package main

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

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

    // Name 和 Comment 写入 gzip 头部，不会成为解压正文。
    zw.Name = "report.txt"
    zw.Comment = "daily export"

    // 写入正文后必须关闭 Writer，Close 会补齐压缩尾部。
    if _, err := zw.Write([]byte("report body")); err != nil {
        return nil, err
    }
    if err := zw.Close(); err != nil {
        return nil, err
    }
    return buf.Bytes(), nil
}

func main() {
    if _, err := buildGZIP(); err != nil {
        log.Fatal(err)
    }
}

在首个 Write 前设置字段

gzip.NewWriter 返回后，Header 字段仍可直接通过 Writer 访问。Go 官方文档明确说明，调用方必须在首次 Write、Flush 或 Close 前设置 Header；一旦头部已经写出，再修改字段就不会回写到已经产生的 gzip 数据。

实际项目中可以把“创建 Writer、设置 Header、写正文、关闭 Writer”放在同一个小函数里，减少调用者先写正文后补元数据的机会：

func compressReport(dst io.Writer, body []byte) error {
    zw := gzip.NewWriter(dst)

    // 必须在第一次 Write 前赋值，字段才会进入 gzip 头部。
    zw.Name = "report.txt"
    zw.Comment = "exported by batch job"

    if _, err := zw.Write(body); err != nil {
        // 写入失败时关闭仍可释放内部资源，但保留原始错误。
        _ = zw.Close()
        return err
    }
    // Close 同时刷新缓冲数据并写入 gzip 尾部。
    return zw.Close()
}

如果目标只是压缩网络响应，Flush 也可能提前触发头部写入，所以不要把设置 Header 延后到第一次 Flush 之后。

处理字符串编码和长度边界

Header 的字符串限制是这类代码最容易忽略的地方。Go 文档要求字符串采用 UTF-8，但可用码点范围只有 U+0001 至 U+00FF；ASCII 字符当然满足要求，Latin-1 范围内的字符也可以使用。中文通常超出这个范围，直接放入 Name 或 Comment 不适合作为稳定的 gzip 头部值。

更稳妥的做法是使用英文或 ASCII 文件名，把中文说明放到应用自己的元数据中；如果业务必须保留中文原名，应在 gzip 之外维护映射关系，而不是假设所有解压工具都会按同一种方式解释扩展字段。

func validHeaderText(s string) bool {
    for _, r := range s {
        // gzip Header 允许 U+0001 到 U+00FF，不接受 NUL 和更大的码点。
        if r  0xFF {
            return false
        }
    }
    return true
}

func setHeader(zw *gzip.Writer, name, comment string) error {
    // 先检查元数据，再开始写正文，避免生成不可互操作的头部。
    if !validHeaderText(name) || !validHeaderText(comment) {
        return errors.New("gzip header text must use U+0001..U+00FF")
    }
    zw.Name = name
    zw.Comment = comment
    return nil
}

空字符串可以表示不设置对应字段；校验函数也应允许空字符串。需要注意的是，这里只解决 Header 的字符范围，不替代对文件名长度、路径清理和业务命名规则的检查。

在读取端取回元数据

读取 gzip 时，gzip.NewReader 返回的 Reader 已经填充了 Header，可以直接读取 zr.Name 和 zr.Comment。Reader 的职责仍然是解压正文；读取元数据并不等于正文已经被完整消费，若需要让 gzip 校验真正完成，仍应继续读到 io.EOF，最后关闭 Reader。

func readHeader(src io.Reader) error {
    zr, err := gzip.NewReader(src)
    if err != nil {
        return err
    }
    defer zr.Close()

    // NewReader 成功后 Header 已可读；这里仅展示元数据取值。
    name := zr.Name
    comment := zr.Comment
    _ = name
    _ = comment

    // 继续读完正文，让 Reader 有机会报告校验错误。
    _, err = io.Copy(io.Discard, zr)
    return err
}

如果一个输入包含多个 gzip member，默认 Reader 会按多流方式处理，但 Reader 字段只记录第一个头部。需要逐个读取 member 时，应结合 Multistream(false) 和 Reset 设计循环，而不要把一个 Reader 的 Header 当成整段输入的所有元数据。

复用 Writer 时重新覆盖 Header

Writer.Reset 适合在循环中复用压缩器，但下一份 gzip 数据仍然要重新设置 Name 和 Comment。Reset 只重置 Writer 的内部状态，不应被理解为“自动替换成下一份文件的元数据”。每次都按“Reset → 设置 Header → Write → Close”的顺序组织即可。

func writeMembers(dst io.Writer, items []struct {
    name string
    body []byte
}) error {
    zw := gzip.NewWriter(dst)
    for i, item := range items {
        if i > 0 {
            // 上一个 member 已 Close，这里复用 Writer 写下一段数据。
            zw.Reset(dst)
        }
        zw.Name = item.name
        zw.Comment = "member metadata"
        if _, err := zw.Write(item.body); err != nil {
            return err
        }
        if err := zw.Close(); err != nil {
            return err
        }
    }
    return nil
}

这段结构的重点不是多流格式本身，而是每次开始新的 gzip member 前重新赋值。若不需要多 member，也可以为每个文件创建独立 Writer，代码更直观。

常见误区与速查表

归纳起来，Go gzip Header 的设置只有三个关键点：字段属于文件头、赋值必须早于首次触发写入、字符串必须符合格式范围。把这三点固定进压缩函数的顺序里，文件名和注释就能稳定地被读取端获取。

相关问题

gzip Header 的 Name 会影响解压后的文件名吗？

它只是 gzip 元数据。最终是否用它作为落盘文件名，取决于解压工具和调用方策略，不能把它当成跨工具一致的文件保存协议。

为什么设置了 Comment 但工具里看不到？

Comment 是可选头部字段，不同工具可能不展示；还要确认它是在首次 Write、Flush 或 Close 之前设置，并且值满足字符范围。

Writer.Close 会关闭底层文件吗？

不会。它负责刷新 gzip 数据并写入尾部，底层 io.Writer 的关闭仍由调用方负责。