Go time.LoadLocation 怎样加载部署环境时区

如果 Go 程序在开发机上能把 Asia/Shanghai 加载出来，部署到精简容器后却报 unknown time zone，问题通常不在 time.Time，而在运行环境没有可用的 IANA 时区数据库。

官方资料：https://pkg.go.dev/time

time.LoadLocation 的核心模式可以概括成“配置使用 IANA 名称，部署提供时区数据，代码显式处理错误”。系统镜像已经带 tzdata 时直接读取；无法保证系统文件存在时，由主程序导入 time/tzdata 作为内置兜底。不要把真实地区时区随手替换成固定小时偏移。

先用 IANA 名称拿到 Location

最小写法是把业务配置中的时区名称直接传给 time.LoadLocation，然后检查错误。Asia/Shanghai、Europe/Berlin 这类名称描述的是一组随日期变化的时区规则，而不是一个永远不变的秒数。

package main

import (
	"fmt"
	"time"
)

func main() {
	loc, err := time.LoadLocation("Asia/Shanghai")
	if err != nil {
		// 时区数据不可用时不要默默改成 UTC，先让部署问题暴露出来。
		panic(err)
	}

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

空字符串和 UTC 会得到 UTC，Local 会得到进程的本地时区。对于可配置的业务地区，建议把完整 IANA 名称放在配置中，而不是把 Local 当作跨环境的默认答案。

理解 LoadLocation 的数据源阶梯

LoadLocation 读取的是 IANA 时区数据库。官方文档给出的查找来源包括 ZONEINFO 指向的目录或未压缩 zip、Unix 系统的标准安装位置、$GOROOT/lib/time/zoneinfo.zip，以及程序导入的 time/tzdata。因此，调用代码相同，运行环境不同，结果也可能不同。

这解释了一个常见现象：完整发行版的开发机通常拥有系统时区目录，而极简镜像只保留运行程序所需的少量文件。如果镜像没有 tzdata，程序仍能启动，但第一次加载非 UTC 地区时区时才暴露错误。

环境变量 ZONEINFO 适合部署方明确提供一套时区数据目录或 zip；它是运行时配置，不应在代码里拼接成某台机器的私有路径。若用它解决镜像问题，要把路径纳入部署配置和升级责任。

为部署环境选择系统文件或内置 tzdata

有两种清晰的工程策略。第一种是在镜像或操作系统层安装 tzdata，让程序使用平台维护的时区数据库；第二种是在主程序中导入 time/tzdata，让 Go 在找不到系统文件时使用嵌入的数据。后者会增加二进制体积，但能减少对运行时文件布局的依赖。

package main

import (
	"fmt"
	"time"
	_ "time/tzdata"
)

func main() {
	loc, err := time.LoadLocation("Europe/Berlin")
	if err != nil {
		// 内置 tzdata 也无法提供合法名称时，继续返回真实错误。
		panic(err)
	}

	name, offset := time.Now().In(loc).Zone()
	fmt.Printf("zone=%s offset=%d\n", name, offset)
}

官方对 time/tzdata 的建议是由主程序决定是否包含它，库不要替调用方做这个选择。也可以在构建时使用 timetzdata 标签启用嵌入方案。选择哪种方式，取决于镜像是否能稳定携带系统文件、是否接受额外体积，以及谁负责跟进时区数据库更新。

错误处理要比“能跑”更重要

加载失败时最不安全的处理是忽略 error，或者把任意地区改成 UTC 后继续写入账单、排班和报表。UTC 是一种明确的业务选择，不是时区数据库缺失时的隐形修复。

func loadBusinessLocation(name string) (*time.Location, error) {
	if name == "" {
		return nil, fmt.Errorf("business time zone is required")
	}

	loc, err := time.LoadLocation(name)
	if err != nil {
		// 保留原始错误上下文，方便区分名称拼写错误和部署缺少数据。
		return nil, fmt.Errorf("load time zone %q: %w", name, err)
	}
	return loc, nil
}

上面的函数没有擅自替换默认时区，也没有把名称错误伪装成环境成功。配置入口可以在启动阶段调用它，让问题尽早失败；如果产品确实规定 UTC 兜底，应在配置文档中显式写出这一业务规则，并记录发生过兜底。

不要用 FixedZone 冒充真实地区规则

time.FixedZone 只表达一个固定名称和固定偏移，适合协议字段、测试夹具或已经确定为固定偏移的场景。它不能替代 Asia/Shanghai、America/New_York 等 IANA 地区，因为地区规则可能包含历史变化和夏令时边界。

func zoneForReport(name string) (*time.Location, error) {
	// 报表按地区规则计算时，优先使用 IANA 名称而不是手工拼 offset。
	loc, err := time.LoadLocation(name)
	if err != nil {
		return nil, fmt.Errorf("report location %q: %w", name, err)
	}
	return loc, nil
}

func zoneForProtocol() *time.Location {
	// 只有协议明确规定固定偏移时，FixedZone 才是合适的表达。
	return time.FixedZone("UTC+08", 8*60*60)
}

另一个反例是把 time.Local 当成服务器所在地区。容器、云主机和开发机的本地配置可能不同；只有业务明确要求“跟随宿主机”时才使用它。对订单、账期和排班这类数据，地区应该成为显式配置或数据字段。

用一张清单决定部署策略

判断顺序可以很简单：先确认配置是否是合法的 IANA 名称，再确认部署是否提供数据库，最后决定由系统文件、ZONEINFO 还是 time/tzdata 承担数据来源。不要先修改代码绕过一个尚未解释的加载错误。

常见相关问题

为什么开发机成功，容器里失败？

最常见原因是容器没有系统 tzdata，且二进制没有可用的内置时区数据。检查镜像策略并在系统文件、ZONEINFO 或 time/tzdata 中选定一个来源。

能不能把所有失败都改成 UTC？

只有业务明确规定 UTC 兜底时才可以。否则会把配置拼写错误和部署缺数据隐藏起来，导致时间被解释到错误的地区。

什么时候应该用 FixedZone？

当协议或测试明确要求恒定偏移时使用。只要需求说的是某个真实地区，就应优先使用 IANA 名称和 LoadLocation。

库要不要直接导入 time/tzdata？

通常不要。是否把时区数据库嵌入程序属于应用和部署决策，应由主程序根据体积、镜像和更新责任决定。