Python zoneinfo 怎样让进程使用自定义时区数据库

如果部署环境没有完整的 IANA 时区数据库，Python 的 zoneinfo.ZoneInfo 可能抛出 ZoneInfoNotFoundError。要让一个进程使用自定义时区目录，优先在进程启动前设置 PYTHONTZPATH；测试代码需要临时切换时，再使用 reset_tzpath()。两者都只接受绝对路径，且后者不会自动清空已经存在的 ZoneInfo 缓存。

官方地址：https://docs.python.org/3/library/zoneinfo.html

生产部署优先把时区数据作为环境或依赖的一部分固定下来：有系统 IANA 数据就明确目录，没有就声明第一方 tzdata 依赖。reset_tzpath() 更适合测试隔离，不适合在业务代码中频繁改全局搜索路径。

ZoneInfo 到底从哪里读取时区数据

zoneinfo 本身不携带完整时区文件。调用 ZoneInfo("Asia/Shanghai") 时，模块先按 TZPATH 中的目录寻找同名 IANA TZif 文件；如果系统目录没有匹配项，再尝试已安装的第一方 tzdata 包。两个来源都没有时，才会抛出 ZoneInfoNotFoundError。

这意味着“能导入 zoneinfo”不等于“所有时区都能构造”。容器、精简 Linux 镜像和 Windows 环境尤其需要把数据来源当作部署依赖处理。ZoneInfo 的 key 是类似 Asia/Shanghai 的相对规范路径，不应写成带上级目录的任意文件路径。

用 PYTHONTZPATH 配置进程启动时的搜索目录

PYTHONTZPATH 是由 os.pathsep 分隔的绝对目录列表。它在模块初始化或无参数调用 reset_tzpath() 时参与设置搜索路径。Linux 和 macOS 通常使用冒号分隔，Windows 使用分号分隔，因此不要把分隔符硬编码成某一个平台的写法。

# 用部署环境提供的绝对目录覆盖本进程的时区搜索路径
export PYTHONTZPATH="/opt/app/share/zoneinfo:/usr/share/zoneinfo"

# 如果只想使用 tzdata，而不读取系统时区目录，可设置为空字符串
export PYTHONTZPATH=""

应用代码可以读取当前路径并构造时区对象，便于把配置问题尽早暴露在启动阶段：

import zoneinfo
from datetime import datetime

# 先打印模块实际看到的绝对搜索目录，便于定位容器配置
print("TZPATH:", zoneinfo.TZPATH)

try:
    shanghai = zoneinfo.ZoneInfo("Asia/Shanghai")
    now = datetime.now(shanghai)
    print(now.isoformat())  # 只展示带时区的时间，不手工拼接偏移量
except zoneinfo.ZoneInfoNotFoundError:
    # 数据源缺失时让启动检查失败，而不是静默使用错误时区
    raise RuntimeError("IANA time zone data is unavailable")

环境变量中的相对路径不会作为可靠配置使用；CPython 会过滤这类组件并发出 InvalidTZPathWarning。因此容器镜像里应复制明确目录，或直接安装 tzdata，而不是依赖当前工作目录。

用 reset_tzpath 在测试中临时切换路径

运行时可以把绝对目录序列传给 reset_tzpath()。这个函数改变的是模块级搜索路径，适合测试需要固定数据目录或验证“没有系统时区数据”这类场景。它不是普通业务请求级配置，多个线程同时改它会让测试和诊断变得难以推断。

from pathlib import Path
from zoneinfo import ZoneInfo, reset_tzpath

# 测试夹具传入绝对目录；Path.resolve() 避免把相对路径传给 zoneinfo
fixture_dir = Path("tests/fixtures/zoneinfo").resolve()
reset_tzpath([fixture_dir])

try:
    # 只有在缓存未命中时，ZoneInfo 才会按新 TZPATH 查找文件
    berlin = ZoneInfo("Europe/Berlin")
    print(berlin.key)  # 输出 key，确认对象对应的 IANA 名称
finally:
    # 无参数会恢复解释器默认搜索路径，避免污染后续测试
    reset_tzpath()

reset_tzpath() 的参数必须是路径序列，而不是一个字符串；传入字符串很容易把每个字符误当作路径元素，也不符合接口约定。所有路径必须是绝对路径，违反时会得到 ValueError。

reset_tzpath 为什么可能看起来没有生效

关键边界是缓存：reset_tzpath() 不会主动使 ZoneInfo 构造器缓存失效。如果某个 key 已经被构造过，后续再次调用 ZoneInfo(key) 可能直接命中旧对象；只有缓存未命中时，新的 TZPATH 才会参与查找。

from zoneinfo import ZoneInfo, reset_tzpath

# 测试中明确清理指定 key，确保下一次构造真的走新路径
ZoneInfo.clear_cache(only_keys=["Europe/Berlin"])
reset_tzpath(["/absolute/path/to/test-zoneinfo"])

# 清理动作只应出现在可控的测试或隔离初始化阶段
zone = ZoneInfo("Europe/Berlin")
print(zone.key)  # 新对象会在缓存未命中后查询当前 TZPATH

清理缓存会改变已有日期对象后续使用的缓存语义，不能为了“刷新一下”在生产业务热路径中随意调用。更稳妥的做法是让每个测试进程使用独立解释器，或在测试夹具的 setup/teardown 中成对设置和恢复路径。

跨平台部署时怎样选择方案

最终判断可以压缩成一句话：部署配置用环境变量或依赖锁定，测试隔离才用运行时切换；遇到“路径已改但结果没变”，先排查缓存，而不是继续增加目录。

常见问题

PYTHONTZPATH 可以写相对路径吗？

不应这样做。官方约定要求绝对路径；相对组件会被忽略或触发实现相关的警告，不能作为跨环境稳定配置。

安装 tzdata 后还需要设置 PYTHONTZPATH 吗？

通常不需要。找不到系统文件时，zoneinfo 会尝试第一方 tzdata 包；只有要强制使用某个目录或做固定数据测试时，才需要显式设置路径。

为什么 reset_tzpath 后 ZoneInfo 还是旧结果？

最常见原因是同一个 key 已在缓存中。测试场景可以在受控范围内调用 ZoneInfo.clear_cache(only_keys=[...])，并避免在并发业务请求中修改全局路径。