Python zoneinfo部署时区数据缺失的兼容处理

zoneinfo 模块提供的是 IANA 时区对象，并不把时区数据库打包进 Python。部署后出现 ZoneInfoNotFoundError，通常不是代码写错，而是运行环境既没有系统时区数据，也没有安装第一方 tzdata 包。跨平台项目最稳妥的做法，是把 tzdata 写进运行依赖，并在启动阶段探测业务必需的时区。

官方文档：https://docs.python.org/3/library/zoneinfo.html

ZoneInfo(key) 会先搜索 TZPATH，找不到时再回退到 tzdata。两处都没有目标数据，才会抛出 ZoneInfoNotFoundError。

先理解系统数据与 tzdata 的两级来源

Linux 发行版通常在 /usr/share/zoneinfo 等位置提供 IANA 数据，但精简容器可能主动删除它；Windows 也没有相同的标准目录。Python 会依次检查 zoneinfo.TZPATH 中的目录，然后尝试读取已安装的 tzdata。因此，不能只在开发机上构造一次 ZoneInfo("Asia/Shanghai") 就认为生产环境一定可用。

把 tzdata 和启动探测一起交付

仅在开发依赖里安装 tzdata 不够，构建生产镜像时也必须保留它。可以在 requirements.txt 或项目依赖表中声明 tzdata，再用一个短探测覆盖业务真正使用的时区。探测成功只代表所列键可用，不代表所有时区或未来规则永远不变。

from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

REQUIRED_ZONES = ("UTC", "Asia/Shanghai", "Europe/Berlin")

def verify_time_zone_data() -> None:
    # 启动时只探测业务依赖的 IANA 键，尽早暴露镜像缺包问题
    missing: list[str] = []
    for key in REQUIRED_ZONES:
        try:
            ZoneInfo(key)
        except ZoneInfoNotFoundError:
            missing.append(key)
    if missing:
        # 错误信息保留缺失键，便于定位依赖或镜像层问题
        raise RuntimeError(f"缺少时区数据: {', '.join(missing)}")

依赖安装与探测应出现在同一构建链路里。这样即使基础镜像更换、系统时区包被裁剪，问题也会在启动阶段暴露，而不是等到某个用户首次选择海外时区时才出现。

只有特殊镜像才调整 TZPATH

自建运行时可能把 IANA 文件放在专用目录，此时可以用 PYTHONTZPATH 配置绝对路径。该变量由 os.pathsep 分隔，不能依赖相对路径。把它设置为空字符串，会让 Python 忽略系统数据并直接尝试 tzdata，适合测试回退逻辑，但不建议在不了解镜像内容时随意启用。

# 仅当镜像确实把 IANA 数据复制到此目录时设置
export PYTHONTZPATH=/opt/app/share/zoneinfo
python -m app

测试代码也可以调用 reset_tzpath() 临时改变搜索路径，但它不会自动清空已经构造的 ZoneInfo 缓存。需要隔离测试时，应先明确缓存边界，不要把运行期改路径当作常规业务配置。

上线前按故障类型检查

• 构建产物里确认 tzdata 位于运行依赖，而不是只存在于开发环境。
• 在与生产一致的镜像中执行必需时区探测，不用本机结果替代。
• 若使用自定义目录，确认 PYTHONTZPATH 全部为绝对路径。
• 捕获 ZoneInfoNotFoundError 时记录时区键，但不要静默改成固定 UTC，以免业务时间含义被悄悄改变。

常见问题

安装 tzdata 后还要设置 PYTHONTZPATH 吗？通常不需要。系统路径找不到时，ZoneInfo 会自动尝试第一方 tzdata 包。

为什么容器本地正常，换基础镜像就报错？不同镜像保留的系统时区包不同。应把 tzdata 纳入应用依赖，并在最终镜像中执行启动探测。