zoneinfo 怎样使用本地时区

Python 里要使用本地时区，核心不是手动写死“东八区”这样的偏移量，而是用 zoneinfo.ZoneInfo 加载 IANA 区域名，例如 Asia/Shanghai。这样得到的 datetime 才能携带时区规则，跨夏令时区域也不会把固定偏移误当成完整时区。

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

用 IANA 区域名创建带时区时间

ZoneInfo 的参数是 IANA 时区键，不是“UTC+8”这类自定义字符串。对于中国大陆业务，Asia/Shanghai 是清晰的区域键；如果业务面向纽约、巴黎等地区，也应保存对应区域名。

from datetime import datetime
from zoneinfo import ZoneInfo

LOCAL_TZ = ZoneInfo("Asia/Shanghai")  # 使用 IANA 区域名，不手写固定偏移
now_local = datetime.now(LOCAL_TZ)  # 直接得到带时区信息的本地时间
print(now_local.isoformat())  # 输出包含日期、时间和 UTC 偏移

关键结果是 now_local.tzinfo 不为空，比较和格式化时也能使用真实的时区规则。不要把 datetime.now() 得到的 naive 时间直接当成可跨地区传输的时间。

区分 replace 与 astimezone 的语义

这是最容易出错的一层。假设字符串里的钟面值“2026-10-25 09:00”本来就代表上海时间，先解析为 naive 值，再用 replace 贴上上海时区标签是合理的；但如果这个值已经代表 UTC，或者已经是另一个区域的时间，就应该用 astimezone 转换。

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

shanghai = ZoneInfo("Asia/Shanghai")  # 目标展示区域
utc_time = datetime(2026, 10, 25, 1, 0, tzinfo=timezone.utc)  # 已明确是 UTC
local_time = utc_time.astimezone(shanghai)  # 保持同一瞬时点，只改变显示区域

wall_clock = datetime(2026, 10, 25, 9, 0)  # 这个钟面值已约定为上海当地时间
localized = wall_clock.replace(tzinfo=shanghai)  # 只贴标签，不做时刻换算
print(local_time.isoformat(), localized.isoformat())  # 两者语义来源不同

可以记成一句话：replace 负责“我确认这个钟面属于哪个区域”，astimezone 负责“这个瞬时点在另一个区域几点”。把二者混用，会造成固定小时数的偏移。

补齐系统时区库与 tzdata 回退

zoneinfo 本身不携带完整时区数据库。它先查系统时区目录，找不到时再尝试第一方 tzdata 包；精简容器、Windows 环境或自定义 Python 构建可能没有系统数据。生产项目可以把 tzdata 写进依赖文件，并在边界处给出明确错误。

from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

def get_timezone(key: str) -> ZoneInfo:
    try:
        return ZoneInfo(key)  # 按 IANA 键查找系统数据或 tzdata
    except ZoneInfoNotFoundError as exc:
        # 将环境问题变成可定位的部署错误，避免默默退回固定偏移
        raise RuntimeError(f"缺少时区数据，请安装 tzdata: {key}") from exc

user_tz = get_timezone("Europe/Berlin")  # 业务层只传递明确的区域键

检查清单可以压缩成三项：

用 fold 处理夏令时重复时间

在发生回拨的地区，同一个本地钟面时间可能出现两次。比如洛杉矶从夏令时切回标准时间时，01:00 既可能带 -07:00，也可能带 -08:00。fold=0 表示切换前，fold=1 表示切换后。

from datetime import datetime
from zoneinfo import ZoneInfo

los_angeles = ZoneInfo("America/Los_Angeles")  # 选择会发生回拨的区域
first = datetime(2020, 11, 1, 1, 0, tzinfo=los_angeles, fold=0)  # 回拨前的 01:00
second = first.replace(fold=1)  # 回拨后的另一个 01:00
print(first.utcoffset(), second.utcoffset())  # 两个钟面值对应不同偏移

如果时间是从 UTC 转到本地，优先让 astimezone 根据时区规则设置正确的 fold；只有用户输入了一个重复的当地钟面值时，才需要在业务规则中要求用户选择前后哪一次。

存储与展示边界怎么定

比较、排序和持久化最好统一用带时区的 UTC；到了报表、通知或页面展示层，再根据用户区域调用 astimezone。区域键可以作为用户偏好保存，但不要把“当前偏移量”当成长期配置，因为偏移量无法表达历史和未来的规则变化。

常见问题

zoneinfo 支持哪些时区名称？

使用 IANA 区域键，例如 Asia/Shanghai、Europe/Berlin。不要把带空格的中文城市名直接传给 ZoneInfo。

为什么本地机器正常，容器里却找不到时区？

容器可能没有系统 IANA 数据，且项目未安装 tzdata。把它声明为运行依赖，并保留 ZoneInfoNotFoundError 的错误信息。

replace 能不能替代 astimezone？

不能。前者只改变 tzinfo 标签，后者按规则换算同一个瞬时点；只有确认 naive 钟面值的所属区域时才用 replace。