Python zoneinfo 找不到时区数据库时怎么部署

部署到 Windows、精简 Linux 镜像或某些 CI 环境后，ZoneInfo("Asia/Shanghai") 抛出 ZoneInfoNotFoundError，通常不是 Python 代码写错，而是运行环境没有可查找的 IANA 时区数据库。zoneinfo 会先查系统时区目录，找不到后再尝试第一方 tzdata 包；两处都没有数据时才会失败。

最稳妥的跨平台做法是把 tzdata 写进项目运行依赖；Linux 容器同时安装系统 tzdata，只有自定义数据目录或测试隔离时才配置 PYTHONTZPATH。

先判断 zoneinfo 缺的是系统数据还是 Python 依赖

故障现场先保留具体的时区 key，不要一看到异常就修改业务时区。ZoneInfo 接收的是 IANA 名称，例如 Asia/Shanghai、Europe/Paris，不是“北京时间”这类展示名称。

from zoneinfo import ZoneInfo, ZoneInfoNotFoundError, TZPATH

try:
    shanghai = ZoneInfo("Asia/Shanghai")  # 这里检查 IANA 数据文件是否可达
except ZoneInfoNotFoundError as exc:
    print(f"时区数据缺失: {exc}")  # 记录 key，便于定位部署环境
else:
    print(shanghai)
    print("当前搜索目录:", TZPATH)  # 只观察路径，不在业务代码里偷偷改全局配置

如果 key 拼写错误，补装依赖也不会解决问题；如果多个合法 key 都失败，再检查依赖和系统目录。官方文档说明，Windows 通常没有“约定俗成”的 IANA 数据目录，因此跨平台项目不应只依赖操作系统。

用 tzdata 把部署环境补齐

应用需要支持 Windows、Linux 和容器时，最简单的修复是把第一方 tzdata 写入生产依赖，而不是只在开发机上执行一次安装命令。

# requirements.txt：与应用一起安装 IANA 时区数据
tzdata

# 重新创建环境后验证一个常用 IANA key
python -c "from zoneinfo import ZoneInfo; print(ZoneInfo('Asia/Shanghai'))"

在 Linux 容器里还可以安装发行版提供的系统包。下面以 Debian/Ubuntu 系镜像为例；Alpine、Fedora 等发行版的包管理器和包名应按基础镜像文档调整。

FROM python:3.14-slim

# 系统包让 zoneinfo 能从标准目录读取数据，并清理 apt 缓存
RUN apt-get update \
    && apt-get install -y --no-install-recommends tzdata \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r /app/requirements.txt

只有自定义时区目录时再调整 PYTHONTZPATH

PYTHONTZPATH 是搜索路径，不是某个具体时区文件的路径。它由多个绝对目录组成，使用当前平台的路径分隔符；设置为空字符串，则可以测试“忽略系统数据、只走 tzdata 回退”的行为。

# Linux/macOS：让测试优先使用项目打包的时区目录
PYTHONTZPATH="/opt/app/share/zoneinfo" python -c \
  "from zoneinfo import ZoneInfo, TZPATH; print(TZPATH); print(ZoneInfo('Asia/Shanghai'))"

# 测试 tzdata 回退路径；空值不是相对路径
PYTHONTZPATH="" python -c "from zoneinfo import ZoneInfo; print(ZoneInfo('Asia/Shanghai'))"

不要把 ./zoneinfo 直接放入该变量。相对路径会被忽略或触发 InvalidTZPathWarning。运行时的 reset_tzpath() 适合测试函数切换目录，不建议在业务请求中反复修改模块全局状态；已有缓存对象也不会因为切换路径自动失效。

发布前的跨平台检查清单

把下面四项放进 CI 或镜像构建后的冒烟检查：依赖文件包含 tzdata；构造一个真实业务会用到的 IANA key；打印一次 zoneinfo.TZPATH；分别在干净虚拟环境和最终镜像中执行验证。这样能把“开发机有数据、生产机没有”的差异提前暴露。

常见问题

安装了 tzdata 还报 ZoneInfoNotFoundError，先查什么？

先确认安装到了当前 Python 解释器对应的环境，再确认 key 是合法 IANA 名称，最后查看 PYTHONTZPATH 是否误指向了不存在或相对路径。

只安装操作系统 tzdata 够不够？

在固定的 Linux 发行版上通常够用，但跨平台发布时建议同时声明 Python 的 tzdata，让 Windows 和缺少系统目录的运行时也有回退数据。

能不能把时区文件复制到项目里再手动读取？

除非确实需要自定义数据目录，否则不建议绕开 zoneinfo。优先使用系统数据或第一方 tzdata，并把数据版本随依赖管理。

为什么不建议在每个请求里调用 reset_tzpath？

它会修改模块级搜索路径，且不会自动清理 ZoneInfo 缓存。部署配置应在进程启动前完成，运行时切换只留给隔离测试。