Go 精简容器加载时区失败怎么办

Go 精简容器里调用 time.LoadLocation("Asia/Shanghai") 失败，通常不是 Go 的时间计算出错，而是运行时找不到 IANA 时区数据库。先保留原始错误，再检查镜像是否有 tzdata；如果镜像必须保持极简，可以在主程序中导入 time/tzdata，让 Go 在系统文件缺失时使用嵌入数据。

官方文档：https://pkg.go.dev/time

最稳妥的处理是：使用可维护的基础镜像时安装系统 tzdata；无法依赖操作系统文件时，在主程序导入 time/tzdata。不要把固定的 FixedZone 当成真实 IANA 时区的替代品。

先确认失败发生在时区数据还是名称

UTC 和 Local 有特殊处理，像 Asia/Shanghai、Europe/Berlin 这样的名称才需要读取 IANA 数据。先用一个小函数把输入和错误写进日志，避免只看到“时间不对”就修改业务逻辑。

package main

import (
    "fmt"
    "time"
)

func loadZone(name string) (*time.Location, error) {
    // 保留原始名称和错误，便于区分拼写问题与镜像缺数据。
    loc, err := time.LoadLocation(name)
    if err != nil {
        return nil, fmt.Errorf("load timezone %q: %w", name, err)
    }
    return loc, nil
}

func main() {
    // IANA 名称必须使用地区/城市形式，不能写成随意的中文名称。
    loc, err := loadZone("Asia/Shanghai")
    if err != nil {
        panic(err)
    }
    fmt.Println(time.Now().In(loc).Format(time.RFC3339))
}

如果名称改成 Asia/Shanghai 后仍失败，再看容器环境；这时重点不是格式化布局，而是时区数据来源。

精简容器里的查找顺序

官方 time.LoadLocation 会依次尝试 ZONEINFO 指向的目录或 zip、Unix 系统标准目录、$GOROOT/lib/time/zoneinfo.zip，以及程序已导入的 time/tzdata。distroless、scratch 或极简 Alpine 镜像经常没有系统 tzdata，因此本地构建正常、容器运行失败并不矛盾。

排查时只看三件事：实际运行的镜像是否包含时区文件；ZONEINFO 是否覆盖了预期来源；最终二进制是否真的由主程序导入了 time/tzdata。不要把宿主机的 /usr/share/zoneinfo 是否存在当成容器内部已经存在。

两种修复方式：安装数据或嵌入数据

如果镜像仍有包管理器，安装系统 tzdata 更直观，也便于随基础镜像更新时区规则。下面以 Debian/Ubuntu 类镜像为例，命令中的注释说明了它的边界。

FROM golang:1.27 AS build
WORKDIR /src
COPY . .
# 只构建主程序；不要在构建阶段误把时区文件当成运行时文件。
RUN CGO_ENABLED=0 go build -o /out/app ./cmd/app

FROM debian:stable-slim
# 运行时安装 IANA 数据，保证 time.LoadLocation 能读取标准目录。
RUN apt-get update \
    && apt-get install -y --no-install-recommends tzdata \
    && rm -rf /var/lib/apt/lists/*
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]

若运行时必须是 scratch 或不希望依赖系统文件，在主程序包中加入空白导入：

package main

import (
    "fmt"
    "time"

    // 将 IANA 时区数据嵌入二进制；仅主程序决定是否承担这部分体积。
    _ "time/tzdata"
)

func main() {
    // 找不到系统 tzdata 时，time 包会回退到嵌入数据。
    loc, err := time.LoadLocation("Asia/Shanghai")
    if err != nil {
        panic(fmt.Errorf("timezone data unavailable: %w", err))
    }
    fmt.Println(time.Now().In(loc))
}

time/tzdata 会增加二进制体积，且官方建议由主程序而不是库来决定是否引入。库只应返回加载错误，不应替宿主应用强行选择数据来源。

上线前的容器复查清单

多阶段构建最容易遗漏的是：修复写在 build 阶段，却没有带到 runtime 阶段；或者运行环境注入了错误的 ZONEINFO。可以把以下检查放进镜像验收脚本：

#!/bin/sh
# 只验证运行时配置和应用自检；不把宿主机目录当作容器证据。
set -eu
printf 'ZONEINFO=%s\n' "${ZONEINFO-}"
/app --check-timezone Asia/Shanghai
# 失败立即退出，让部署系统保留清晰的启动错误。
printf 'timezone check passed\n'

检查结果应能回答：名称是否为 IANA 标准形式、应用是否使用了目标时区、镜像升级后规则是否仍可加载。容器启动失败时先回滚到已知可用镜像，再修复构建定义；不要用固定 UTC 偏移临时掩盖真实的夏令时或历史规则差异。

常见追问

只设置 TZ 环境变量就够了吗？

不一定。TZ 主要影响 Local 的解释；显式加载 IANA 名称仍需要对应的数据来源。

为什么不直接使用 FixedZone？

固定偏移不会表达 IANA 数据中的历史变化或夏令时规则，只适合明确就是固定偏移的业务场景。

我的判断是：能控制镜像内容时安装 tzdata，不能控制时才把 time/tzdata 放进主程序。两者都可行，但必须把数据来源作为部署契约写进构建和启动检查。