Go gzip Header 为什么必须在首次 Write 前修改

因为 gzip.Writer 的 Header 不是在 NewWriter 时立刻写出，而是在首次 Write、Flush 或 Close 时一次性编码到底层输出。字节一旦发出，后续再修改 Name、Comment、Extra、ModTime 或 OS，只会改变 Go 结构体里的值，不会回写已经生成的 gzip 头。

• 正确顺序：NewWriter → 设置全部 Header 字段 → Write → Close。
• 隐藏触发：即使还没 Write，Flush 或 Close 也会固定 Header。
• 复用注意：Reset 后相当于新的 Writer，需要再次设置元数据。

症状：正文正确，Name 和 Comment 却还是旧值

一个常见故障是：压缩正文能正常解开，但接收方看到的文件名、注释或修改时间为空，或者仍然是上一份数据的值。代码往往先写了正文，再补 Header：

zw := gzip.NewWriter(dst)

// 这次 Write 会触发 gzip Header 写入底层输出。
if _, err := zw.Write(payload); err != nil {
    return err
}

// 此时修改已经太晚，不会改变前面写出的 Header 字节。
zw.Name = "report.csv"
zw.Comment = "nightly export"

return zw.Close() // Close 只会完成剩余压缩数据和 footer

根因不在 Reader，也不是 Name 字段被忽略，而是 Header 的序列化时机已经过去。流式 Writer 无法假设底层输出支持随机定位，更不能回到开头覆盖已经发送到文件、网络或管道中的字节。

修复：把 Header 配置集中到首次输出之前

最稳妥的写法是创建 Writer 后立即设置全部元数据，中间不插入任何可能写数据或刷新缓冲区的调用。Go 官方文档明确要求这些字段在首次 Write、Flush 或 Close 前完成设置。

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

    // 所有 Header 元数据都在首次输出前一次性配置。
    zw.Name = "report.csv"
    zw.Comment = "nightly export"
    zw.ModTime = time.Unix(0, 0).UTC()
    zw.OS = 255 // 255 表示未知或跨平台来源

    if _, err := zw.Write(payload); err != nil {
        return fmt.Errorf("写入 gzip 正文: %w", err)
    }
    if err := zw.Close(); err != nil {
        return fmt.Errorf("完成 gzip 输出: %w", err)
    }
    return nil
}

Close 很重要：压缩器可能仍缓存数据，而且 gzip footer 要到结束时才完整写出。它不会替你关闭底层 dst，文件或网络连接仍由调用者负责管理。

Flush 和 Close 也会让 Header 提前固定

故障排查时不要只搜索第一次 Write。有些封装层会为了降低网络延迟先调用 Flush，另一些错误分支会在尚未写正文时直接 Close。这两种情况同样会把 Header 发出，因此随后补字段仍然无效。

Reset 复用时重新设置每一份 Header

Reset 会丢弃当前 Writer 状态，并让它以新的底层输出重新开始。不要把上一轮 Header 当成可靠默认值；每次 Reset 后都执行同一个配置函数，能避免对象池复用时串用文件名和时间。

func configureHeader(zw *gzip.Writer, name string, modTime time.Time) {
    // 每个新 gzip 流都明确设置自己的元数据。
    zw.Name = name
    zw.Comment = "generated export"
    zw.ModTime = modTime.UTC()
    zw.OS = 255
}

zw := gzip.NewWriter(firstDst)
configureHeader(zw, "part-001.csv", firstTime)
// 这里写入并关闭第一份 gzip 流。

zw.Reset(secondDst)
configureHeader(zw, "part-002.csv", secondTime)
// Reset 后重新配置，再开始第二份输出。

Header 的 Name 和 Comment 还有格式限制：它们必须是 UTF-8，并且字符范围受 gzip 格式约束。不要把任意用户输入原样当作跨平台文件名；如果元数据来自外部请求，应先做长度和字符集处理。

常见问题 1：只改 ModTime 也必须放在 Write 前吗？
是。ModTime 与 Name、Comment、Extra、OS 一样都属于 Header，序列化后再改不会进入当前流。

常见问题 2：为什么读取端看到的值和 Writer 结构体当前值不同？
读取端解析的是已发送的 gzip 字节；Writer 结构体后来的内存变化不是协议的一部分。

常见问题 3：可以通过 Seek 回去修补吗？
不建议。gzip.Writer 面向通用 io.Writer，底层可能是网络或管道；正确做法是把配置顺序固定，而不是依赖可回写的特殊输出。

这类问题的防复发关键不是增加更多条件判断，而是收紧所有权：让一个构造函数同时完成 NewWriter 和 Header 配置，并在返回给正文写入逻辑前禁止 Flush、Write 或 Close。调用顺序固定后，元数据丢失就不会再次出现。