Go 读取 IANA 时区失败时怎么处理部署环境差异

在本机执行 time.LoadLocation("Asia/Shanghai") 没问题，换到精简容器却得到 unknown time zone Asia/Shanghai，通常不是 Go 代码突然失效，而是运行环境没有可读取的 IANA 时区数据。处理这类问题的关键是：保留 IANA 名称，先确认数据来源，再决定补系统文件、设置 ZONEINFO，还是把 time/tzdata 编进二进制。

只要目标环境能提供 IANA 数据，LoadLocation 就能按地区规则处理历史偏移和夏令时；不要用一个固定的 time.FixedZone 去掩盖部署缺文件。

先分清布局、时区名称和时区数据

这三个概念经常被混在一起。布局是 "2006-01-02 15:04:05" 这类 Go 格式模板；时区名称是 "Asia/Shanghai"、"America/New_York" 这样的 IANA 标识；时区数据则记录某个地区在不同年份的偏移和切换规则。

因此，下面这段代码在“数据缺失”时会失败，换一个布局并不能修复它：

package main

import (
	"fmt"
	"time"
)

func main() {
	// IANA 名称决定规则来源，不能写成随意的中文地名。
	loc, err := time.LoadLocation("Asia/Shanghai")
	if err != nil {
		// 启动阶段直接暴露环境问题，避免请求运行到一半才发现。
		panic(fmt.Errorf("load timezone: %w", err))
	}

	now := time.Now().In(loc)
	fmt.Println(now.Format("2006-01-02 15:04:05 MST"))
}

如果错误信息包含 unknown time zone，先检查文件来源；如果加载成功但解析结果不对，再检查 ParseInLocation 的输入是否真的没有时区信息。

Go 的时区数据到底从哪里找

官方 time 包给出了明确的查找顺序：先看 ZONEINFO 指向的目录或未压缩 zip，再看 Unix 系统标准目录，然后是 $GOROOT/lib/time/zoneinfo.zip，最后才看是否导入了 time/tzdata。这解释了为什么开发机正常、镜像失败：两者的文件系统和运行时来源不同。

排查时可以把问题拆成三问：容器里有没有对应的 zoneinfo 文件？进程是否设置了意外的 ZONEINFO？构建产物是否导入了 time/tzdata？不要把 TZ 和 ZONEINFO 当成一回事：前者主要影响 time.Local，后者是 LoadLocation 查找数据库的入口。

精简容器里应该怎么补齐

部署策略通常有两条。第一条是在镜像中安装或复制系统时区数据，让应用继续使用操作系统提供的 IANA 文件；这适合多个程序共享运行时数据的场景。第二条是在主程序中导入标准库的 time/tzdata：

package main

import (
	"fmt"
	"time"

	// 把 IANA 数据嵌入二进制，系统没有 zoneinfo 时仍可加载。
	_ "time/tzdata"
)

func loadBusinessLocation(name string) (*time.Location, error) {
	// 让调用方决定如何记录错误，不把失败静默降级为固定偏移。
	loc, err := time.LoadLocation(name)
	if err != nil {
		return nil, fmt.Errorf("load %q: %w", name, err)
	}
	return loc, nil
}

官方文档说明，导入 time/tzdata 会让程序增加大约 450 KB，并建议由主程序决定是否携带它。对 scratch 这类没有常规文件布局的镜像，嵌入通常更直接；对体积敏感且能控制基础镜像的服务，则可以统一维护系统时区包。

用 ParseInLocation 验证真实偏移

加载成功只是第一关。没有显式时区的字符串交给 time.Parse 时按 UTC 解释；如果业务语义是“这个本地时间属于上海”，应该使用 ParseInLocation。它不会把输入文本变成固定偏移，而是让对应的 IANA 规则参与解释。

func parseLocalText(text string, loc *time.Location) (time.Time, error) {
	// 输入没有时区后缀，明确声明它属于 loc，而不是默认按 UTC 解释。
	const layout = "2006-01-02 15:04:05"
	t, err := time.ParseInLocation(layout, text, loc)
	if err != nil {
		return time.Time{}, fmt.Errorf("parse local time: %w", err)
	}
	return t, nil
}

上线前至少做一次启动检查：加载真实业务地区，打印一次 Location 名称和一个带 MST 的格式化结果；再用一组跨季节日期检查偏移是否符合预期。检查失败就让进程启动失败，别在请求路径里反复加载，也别用 FixedZone 把错误包装成“看起来能跑”。

常见问题

只设置 TZ=Asia/Shanghai 能修复 LoadLocation 吗？

不能把它当成通用修复。TZ 主要决定 time.Local，命名时区加载仍需要 IANA 数据来源；应用应显式检查 LoadLocation 的错误。

为什么本机有数据，scratch 容器却没有？

本机通常带有 Unix 系统 zoneinfo 或 Go 工具链目录，scratch 只保留你复制进去的文件。选择复制系统数据或导入 time/tzdata，取决于镜像维护方式。

所有业务时间都能改成固定 UTC 偏移吗？

不能。UTC 适合存储和跨服务传输；需要展示某个地区的历史规则或夏令时变化时，仍应使用 IANA 名称。

把时区问题拆成“名称、数据、解析语义”三层，部署差异就容易定位：先让 LoadLocation 找到数据，再用 ParseInLocation 验证本地时间含义，最后把启动检查放进发布流程。