Go archive/zip.FileHeader.SetModTime 怎样设置 ZIP 条目的修改时间

在 Go 里手动生成 ZIP 条目时，如果希望解压工具看到一个明确的修改时间，可以给 zip.FileHeader 设置时间。旧代码常见的写法是调用 SetModTime；它会把传入值转成 UTC，并同步维护 Modified、ModifiedTime 和 ModifiedDate。不过当前官方文档已经把这个方法标记为弃用，新代码更适合直接设置 Modified。

官方地址：https://pkg.go.dev/archive/zip#FileHeader.SetModTime

如果是在维护已有代码，SetModTime(t) 仍然可以表达“把条目时间设置为 t”；如果是新代码，优先写 header.Modified = t，并把跨工具读取时的时区和两秒精度差异纳入检查。

先看清 SetModTime 到底改了什么

排查“设置了时间但解压后不一致”时，第一步不是换格式化字符串，而是确认字段关系。官方实现会先执行 t.UTC()，再把这个 UTC 时间写入 Modified，同时编码旧式的 ModifiedDate 和 ModifiedTime。因此它不是只改了一个展示字段。

下面这段代码把时间设置和条目创建放在同一处，便于定位问题：

package main

import (
	"archive/zip"
	"bytes"
	"fmt"
	"log"
	"time"
)

func main() {
	var buf bytes.Buffer
	w := zip.NewWriter(&buf)

	// 用固定时区构造业务时间，避免示例依赖机器当前时区。
	loc := time.FixedZone("CST", 8*60*60)
	modified := time.Date(2026, 10, 28, 9, 15, 7, 0, loc)

	h := &zip.FileHeader{Name: "report.txt"}
	// SetModTime 会转成 UTC，并同步旧式 DOS 日期、时间字段。
	h.SetModTime(modified)
	h.Method = zip.Store

	entry, err := w.CreateHeader(h)
	if err != nil {
		log.Fatal(err)
	}
	if _, err := entry.Write([]byte("archive metadata demo\n")); err != nil {
		log.Fatal(err)
	}
	if err := w.Close(); err != nil {
		log.Fatal(err)
	}

	// 这里打印的是内存中的 ZIP 大小，不把它当作时间校验结果。
	fmt.Println("zip bytes:", buf.Len())
}

这里的关键顺序有三个：先准备 FileHeader，再设置时间，之后通过 CreateHeader 创建条目，最后关闭 zip.Writer。如果在条目已经创建后才修改 header，修改通常不会回写到已经写出的条目元数据。

为什么本地时间写进去后看起来变了

SetModTime 的实现会把输入时间转换为 UTC。比如输入是东八区上午 9 点，内部的 Modified 会对应到 UTC 凌晨 1 点。这个转换本身不是时间丢失，而是把时间点统一到一个绝对基准。

同时，ZIP 兼容性存在两条时间路径：写入时 Go 会输出时区无关的扩展时间戳；旧式 MS-DOS 日期和时间字段则按 Modified 的 location 编码。不同解压工具优先读取的字段可能不同，所以同一个条目在老工具里显示的时区和秒数可能与 Go 端打印结果不完全相同。

两秒精度会怎样影响结果

MS-DOS 时间字段的秒数不是按 0 到 59 的每一秒保存，而是用“秒除以 2”的方式编码，分辨率为 2 秒。也就是说，带有奇数秒的时间在旧字段中会发生取整；纳秒也不会进入这个字段。

package main

import (
	"archive/zip"
	"fmt"
	"time"
)

func main() {
	t := time.Date(2026, 10, 28, 9, 15, 7, 987000000, time.FixedZone("CST", 8*60*60))
	h := &zip.FileHeader{Name: "odd-second.txt"}

	// 这个调用保留精确时间点到 Modified，同时填充兼容旧工具的字段。
	h.SetModTime(t)

	fmt.Println("input:", t)
	fmt.Println("stored Modified:", h.Modified)
	fmt.Println("legacy ModTime:", h.ModTime())
}

因此，排查时要先问“读取方拿的是哪个字段”。如果读取方使用扩展时间戳，通常能得到更接近 Modified 的结果；如果只读取 MS-DOS 字段，就要接受两秒分辨率和 UTC 假设带来的差异。不要用字符串格式化后的文本去判断 ZIP 元数据是否正确。

新代码应该直接使用 Modified

当前文档把 SetModTime 标记为 Deprecated，并建议使用 Modified。迁移时可以把设置动作改为直接赋值：

h := &zip.FileHeader{Name: "report.txt"}

// 新代码直接保存业务时间；写入器会根据 Modified 处理 ZIP 时间元数据。
h.Modified = modified
h.Method = zip.Deflate

entry, err := w.CreateHeader(h)
if err != nil {
	return err
}
// 写入正文后再关闭 Writer，确保目录记录被完整写出。
_, err = entry.Write(data)
if err != nil {
	return err
}
return w.Close()

直接使用 Modified 的好处是语义更贴近当前 API，也避免新代码继续依赖旧式字段。不过这不意味着旧 ZIP 读取方突然获得纳秒精度；兼容性仍由 ZIP 读取工具支持的时间字段决定。

按这份清单定位时间不一致

1. 确认时间来源：是文件系统的 ModTime()、业务时间，还是固定时区的测试时间。
2. 确认设置时机：必须在 CreateHeader 之前完成 Modified 或 SetModTime。
3. 确认时区：比较时间点时统一调用 UTC()，不要直接比较不同 location 的格式化字符串。
4. 确认精度：奇数秒和纳秒无法由 MS-DOS 旧字段完整表达。
5. 确认读取方：检查解压工具是否支持并优先读取 ZIP 扩展时间戳。
6. 确认收尾：调用 zip.Writer.Close，否则中央目录可能尚未写完。

常见问题

SetModTime 会把时区信息保存下来吗？

它会把输入转换成 UTC；ZIP 条目中的时间并不是一个可以完整携带 Go time.Location 对象的字段。读取时应把它当作时间点和兼容字段的组合，而不是原样保存的时区名称。

为什么读取后秒数少了一秒？

优先怀疑读取方只使用了 MS-DOS 时间字段。该字段按 2 秒保存，奇数秒会被取整；同时还要确认是否发生了时区转换。

只设置 Modified 就够了吗？

对新代码通常够用，前提是时间要在创建条目前设置，并且最后关闭 Writer。若必须兼容只理解旧字段的工具，应在目标工具上做一次针对性的读取检查，但不要把旧字段精度误认为 Go 时间值的精度。

总结

FileHeader.SetModTime 解决的是“把一个 Go 时间写进 ZIP 条目”的兼容性问题：它转 UTC、同步 Modified 与两个旧字段，而 MS-DOS 字段只有两秒分辨率。维护旧代码时可以继续理解它的字段效果；新代码优先设置 FileHeader.Modified，并在条目创建前完成赋值。遇到显示差异时，按时间来源、设置时机、时区、精度和读取方逐层排查，通常比反复修改格式化代码更快定位原因。