Go compress/gzip Header.ModTime 如何控制归档可复现性

同一份文本连续生成两个 gzip 文件，为什么 SHA-256 还会不同？如果代码把 gzip.Writer 的 ModTime 留成当前时间，答案通常就在 gzip 头部，而不是压缩正文。要让归档具备可复现性，应在第一次写入之前把 Header.ModTime 设成约定好的 UTC 秒级时间；若不需要携带修改时间，则明确使用零值，并同时固定 Name、Comment、Extra 等其他头部字段。

Header.ModTime 控制的是 gzip 头，不是文件内容

compress/gzip 的 Header 暴露了 Name、Comment、Extra、ModTime 和 OS。其中 ModTime 对应 GZIP 规范里的 MTIME：它是归档携带的修改时间元数据。读者解压后看到的文本不会因为它改变，但对完整 gzip 文件做哈希、签名或缓存比较时，头部的几个字节已经不同。

Go 的 Writer 会延迟写 gzip 头。标准库实现是在首次 Write 时写头；Flush 和 Close 在尚未写过数据时也会触发这一步。因此，下面这种顺序才可靠：

package main

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

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

    // 先固定元数据；不能等 Write 或 Flush 之后再改 ModTime。
    zw.ModTime = archiveTime.UTC().Truncate(time.Second)
    zw.Name = "payload.txt"
    zw.Comment = "reproducible example"

    // Write 负责压缩正文，Close 负责写完尾部校验信息。
    if _, err := zw.Write(data); err != nil {
        return nil, fmt.Errorf("write gzip data: %w", err)
    }
    if err := zw.Close(); err != nil {
        return nil, fmt.Errorf("close gzip writer: %w", err)
    }
    return buf.Bytes(), nil
}

// 调用方传入同一个 archiveTime，才有可比较的时间元数据。
var fixedTime = time.Date(2026, time.January, 1, 0, 0, 0, 0, time.UTC)

这里的 Truncate(time.Second) 不是为了改变业务时间，而是把传入值先归一化。gzip 的 MTIME 只保存 Unix 秒，纳秒部分本来就不会进入头部；在进入构建缓存键或测试断言前主动截断，能让“程序里的期望值”和“归档里的实际值”使用同一精度。

先固定时间，再排除其他会漂移的头字段

只设置 ModTime 并不等于整个归档一定可复现。实战中可以按下面的清单排查：

还有一个容易忽略的时机问题：Flush 也可能先把头部写出去，所以“先 Flush 预热，再设置 ModTime”同样不行。若 Writer 被 Reset 复用，要把它当成一次新的归档初始化，重新设置所有需要稳定的 Header 字段。

秒级、零值和时间范围是三个边界

Go 的 gzip 实现把正的 ModTime.Unix() 写入 32 位字段。于是有三条实用规则：

1. 固定时间最好使用 UTC，并先归一化到秒；时区本身不会改变 Unix 秒，但会让配置阅读和排错变得含糊。
2. 零值表示“不携带修改时间”。Unix epoch 以前的时间也不会按负数写进这个无符号字段，不能拿它表达真实的历史时间。
3. 不要把超出 GZIP MTIME 32 位秒范围的时间当成可靠元数据；若业务需要更远的时间，应另存清晰的业务字段。

“使用零值”与“使用固定时间”是两个不同的产品决策。前者适合不希望归档携带时间的缓存产物，后者适合需要保留发布批次或源文件时间的归档。关键不是哪一个更好，而是同一条流水线必须始终采用同一种约定。

读回 Reader.Header.ModTime，确认写入时机没有错

不要只看生成函数里的变量。把字节交给 gzip.NewReader 后读回 Header，能确认归档里真正保存了什么；同时把正文读到 EOF，再关闭 Reader，才能让 gzip 校验完整结束。

func readGZIPTime(blob []byte, want time.Time) error {
    zr, err := gzip.NewReader(bytes.NewReader(blob))
    if err != nil {
        return fmt.Errorf("open gzip reader: %w", err)
    }
    defer zr.Close()

    // Header.ModTime 是归档头中的值，比较时统一到 UTC 秒。
    got := zr.ModTime.UTC().Truncate(time.Second)
    expected := want.UTC().Truncate(time.Second)
    if !got.Equal(expected) {
        return fmt.Errorf("unexpected ModTime: got %s want %s", got, expected)
    }

    // 读到 EOF，才能让 Reader 完成长度和 CRC 校验。
    if _, err := io.Copy(io.Discard, zr); err != nil {
        return fmt.Errorf("read gzip body: %w", err)
    }
    return nil
}

这个检查只能证明时间元数据一致，不能单独证明整文件字节一致。如果目标是可复现构建，还应对两份输出做哈希比较，并逐项确认 Name、Comment、Extra、OS、压缩级别、输入字节顺序和 Go 工具链没有变化。

相关问题

把 ModTime 设为 time.Now() 可以吗？

可以生成合法 gzip，但不适合做可复现归档，因为每次运行的 MTIME 都可能不同。除非时间就是业务元数据，否则应由调用方传入稳定的发布时间或使用零值。

第一次 Write 之后再改 ModTime 为什么不生效？

因为 gzip 头已经写出，后续 Write 只处理压缩正文。把 Header 字段集中设置在第一次写入之前，可以避免这种“变量改了、文件没变”的错觉。

固定 ModTime 后还要固定文件名吗？

要。非空的 Name 也属于 gzip 头部元数据，临时路径、随机后缀或构建编号都会让完整字节继续变化。

gzip 的 ModTime 会改变解压后的文件修改时间吗？

它是 gzip 成员头中的元数据，Reader 可以读回它；是否把这个时间应用到落盘文件，取决于解压工具的行为，不能把两者当成同一件事。