Python zoneinfo.ZoneInfoNotFoundError 怎样处理时区数据缺失

在 Windows、精简容器或自带 Python 的部署环境里，ZoneInfo("Asia/Shanghai") 可能突然抛出 ZoneInfoNotFoundError。这个异常通常不是夏令时计算错了，而是运行环境找不到 IANA 时区数据。排查顺序应该是：先确认时区键，再确认系统数据，最后把一方的 tzdata 纳入依赖；只有确实使用自定义数据库时，才调整查找路径。

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

最稳妥的生产修复是把 tzdata 写进应用依赖，让没有系统时区库的平台也有明确的数据来源，而不是在业务代码里吞掉异常。

• 先区分“键写错”和“数据源缺失”。
• 跨平台发布优先声明 tzdata，路径配置只处理特殊部署。
• 改动 PYTHONTZPATH 或调用 reset_tzpath() 前，先确认绝对路径和缓存边界。

先确认 ZoneInfoNotFoundError 的含义

zoneinfo 使用 IANA 时区数据库。构造 ZoneInfo(key) 时，Python 会先在 TZPATH 指向的系统目录查找；系统数据不可用时，再尝试一方的 tzdata 包。两条来源都找不到对应键，才会抛出这个异常。

from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

try:
    # 使用 IANA 的规范键，不要把显示名称当成查找键。
    shanghai = ZoneInfo("Asia/Shanghai")
except ZoneInfoNotFoundError:
    # 这里表示时区数据不可用，不能用固定偏移静默替代。
    raise RuntimeError("部署环境缺少 IANA 时区数据，请安装 tzdata")

先看键值是否符合 IANA 形式，例如 Asia/Shanghai、Europe/Paris。如果键明显正确，却只在 Windows 或极简镜像中失败，优先怀疑数据包没有随应用发布，而不是去修改日期运算逻辑。

按两条数据来源排查部署问题

我在处理这类问题时，会把“依赖修复”和“路径修复”分开。依赖修复适合大多数应用：在依赖文件中声明 tzdata，由构建系统和发布系统一起安装。

# 将一方时区数据包安装进当前 Python 环境。
python -m pip install tzdata

# 生产项目应把依赖写入 requirements.txt 或 pyproject.toml。
python -m pip freeze | grep '^tzdata=='

不要把上面的临时安装命令当成发布方案；真正上线时应把版本约束写进项目依赖，并让镜像构建或虚拟环境创建阶段安装它。这样做的价值是：系统是否自带时区库不再决定程序能否启动。

如果应用明确要忽略系统数据、只使用 Python 依赖，可以在进程启动前设置空的 PYTHONTZPATH。这是部署策略，不是通用的故障隐藏手段：

# 让 zoneinfo 跳过系统目录，直接尝试 tzdata 包。
export PYTHONTZPATH=""

# 启动应用；变量应在 Python 进程初始化前生效。
python app.py

只在必要时调整 PYTHONTZPATH

当时区数据放在自定义绝对路径，才考虑 PYTHONTZPATH 或 reset_tzpath()。环境变量用于初始化查找路径，运行时函数用于显式修改模块的路径状态；两者都不是替代 tzdata 依赖的第一选择。

from zoneinfo import TZPATH, ZoneInfo, reset_tzpath

# 读取当前查找目录，便于把部署配置记录到诊断日志。
print(TZPATH)

# 只有自定义目录确实存在时才调整路径，并且必须使用绝对路径。
reset_tzpath(["/opt/app/share/zoneinfo"])

# 路径改变后再构造目标时区；示例不代表本机已经有该目录。
tokyo = ZoneInfo("Asia/Tokyo")

这里有两个容易忽略的边界。第一，PYTHONTZPATH 的组件应是绝对路径，不能写成相对目录。第二，reset_tzpath() 不会自动清空 ZoneInfo 缓存；如果你在测试中切换数据目录，需要按官方文档评估缓存清理对现有日期对象的影响。普通业务服务通常不应该在请求处理中反复改路径。

上线前的处理清单

回滚时也保持同样的边界：撤回自定义路径配置，恢复明确的 tzdata 依赖，不要把异常改成固定 UTC 偏移。固定偏移无法表达 IANA 时区的历史规则和夏令时变化。

常见问题

安装了 tzdata 仍然报错，先看什么？

先确认安装它的 Python 环境和启动应用的 Python 环境是同一个，再检查传入的键是否为规范 IANA 名称。不要只看系统的 pip 输出。

什么时候应该使用 reset_tzpath？

只有数据确实位于自定义绝对路径，或测试需要隔离数据目录时才使用。跨平台应用通常直接声明 tzdata 更容易维护。