Python zoneinfo 怎样处理夏令时边界

我在处理跨地区预约时遇到过一个很隐蔽的时间问题：同一个本地时钟读数，有时根本没有发生过，有时却在同一天出现两次。zoneinfo 的正确用法不是把时区名拼到字符串上，而是把 ZoneInfo 绑定到 aware datetime，再对夏令时切换点做一次“是否能从 UTC 往返”的判断。

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

先记住结论：春季拨快时产生的本地时间属于缺失时间，不能直接当成真实时刻保存；秋季拨回时产生的本地时间属于重复时间，要用 fold=0 或 fold=1 选择切换前后不同的 UTC 时刻。真正用于排序、去重和跨地区比较的字段，应当是 UTC aware datetime。

先把问题拆成普通、缺失和重复三类时间

夏令时边界最容易让排查方向跑偏。以 America/Los_Angeles 为例，春季从标准时间切到夏令时，会把一段本地钟面时间直接跳过去；秋季切回标准时间，则会把一段钟面时间再走一遍。普通日期只有一个对应的 UTC 时刻，跳过的时间没有对应时刻，重复的时间则有两个对应时刻。

ZoneInfo 使用 IANA 时区规则。它支持直接附加到 datetime，也支持通过 astimezone() 做跨时区转换；在偏移切换造成歧义时，fold 用来选择切换前或切换后的偏移。

先用 ZoneInfo 创建带时区的 datetime

不要先构造一个 naive datetime，再靠字符串格式猜它属于哪个地区。接收用户输入时，可以先把“日期时间文本”和“地区时区键”作为两个独立字段，然后显式组合。这样日志、数据库和接口都能看出时区来源。

from datetime import datetime
from zoneinfo import ZoneInfo

# 地区键来自 IANA 时区数据库，不能把固定 UTC 偏移当成地区规则。
los_angeles = ZoneInfo("America/Los_Angeles")
local_time = datetime(2026, 11, 1, 1, 30, tzinfo=los_angeles)

# 默认 fold=0，表示重复小时中切换前的那一个实例。
print(local_time.isoformat())
print(local_time.utcoffset())

这里的对象是 aware datetime，能够携带 UTC 偏移。需要注意的是，直接用构造器附加 ZoneInfo 并不会替业务决定缺失时间应该怎样处理，所以春季跳时的输入仍要经过额外判断。

用 UTC 往返找出缺失时间

处理用户输入的本地钟面时间时，可以分别尝试两个 fold 值，并把候选时间转换到 UTC，再转换回原来的地区。如果往返后的钟面值与输入不一致，说明这个本地时间没有真实对应的时刻；如果能往返但两个 fold 产生不同 UTC，说明它是重复时间。

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

def classify_local_time(naive: datetime, zone: ZoneInfo) -> dict:
    # 这个函数只接受没有 tzinfo 的本地钟面时间，避免重复绑定时区。
    if naive.tzinfo is not None:
        raise ValueError("naive 参数不能已经带时区")

    candidates = []
    for fold in (0, 1):
        # fold 只表示重复小时的两个候选偏移，不代表所有时间都有效。
        aware = naive.replace(tzinfo=zone, fold=fold)
        utc_value = aware.astimezone(timezone.utc)
        round_trip = utc_value.astimezone(zone)

        # 往返后仍是同一个钟面值，才说明该候选对应真实时刻。
        if round_trip.replace(tzinfo=None) == naive:
            candidates.append((fold, utc_value))

    if not candidates:
        # 春季跳时产生的区间没有真实时刻，交给业务决定拒绝或调整。
        return {"kind": "missing", "instants": []}

    instants = {value for _, value in candidates}
    if len(instants) == 1:
        # 普通时间的两个 fold 最终会落到同一个 UTC 时刻。
        return {"kind": "normal", "instants": candidates[:1]}

    # 秋季重复小时有两个不同的 UTC 时刻，必须让业务明确选择。
    return {"kind": "ambiguous", "instants": candidates}

zone = ZoneInfo("America/Los_Angeles")
print(classify_local_time(datetime(2026, 3, 8, 2, 30), zone))

这段代码的重点不是记住某个具体年份的切换日期，而是把判断建立在当前 IANA 规则上。对 missing，预约系统通常应提示用户重新选择；对 ambiguous，可以显示两个偏移供用户确认，或者由产品规则固定选择一个。

重复小时用 fold 选定真实时刻

重复小时不能只保存 2026-11-01 01:30 这样的字符串，因为它没有说明是切换前还是切换后。fold=0 使用切换前的偏移，fold=1 使用切换后的偏移。两个对象的本地显示可能一样，但转到 UTC 后不是同一个瞬间。

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

zone = ZoneInfo("America/Los_Angeles")
wall_clock = datetime(2026, 11, 1, 1, 30)

# 同一个钟面时间显式保留两个候选，避免悄悄吞掉用户选择。
before_switch = wall_clock.replace(tzinfo=zone, fold=0)
after_switch = wall_clock.replace(tzinfo=zone, fold=1)

# 用 UTC 表示真实时刻，适合排序、比较和跨地区传输。
print(before_switch.astimezone(timezone.utc).isoformat())
print(after_switch.astimezone(timezone.utc).isoformat())

如果业务是“每年当地时间 01:30 执行一次”，要先定义遇到重复小时执行一次还是两次；如果业务是“每隔固定时长执行”，则应保存上一次的 UTC 时刻并按持续时间计算。两种语义不要混用。

部署时准备 IANA 数据，并保存正确字段

zoneinfo 优先读取系统时区数据，找不到时再尝试第一方的 tzdata 包。尤其是需要跨平台部署的程序，不能假设每台机器都有相同的时区数据库；如果两者都不可用，创建 ZoneInfo 会抛出 ZoneInfoNotFoundError。

from datetime import datetime, timezone
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

def to_storage_fields(utc_value: datetime, zone_key: str, fold: int) -> dict:
    # 存储前强制使用 UTC aware datetime，避免把本地钟面当作瞬间。
    if utc_value.tzinfo is None or utc_value.utcoffset() is None:
        raise ValueError("utc_value 必须是 aware datetime")
    if fold not in (0, 1):
        raise ValueError("fold 只能是 0 或 1")

    try:
        # 启动或配置检查阶段可提前触发时区数据缺失错误。
        ZoneInfo(zone_key)
    except ZoneInfoNotFoundError as exc:
        raise RuntimeError(f"缺少时区数据: {zone_key}") from exc

    return {
        "occurred_at_utc": utc_value.astimezone(timezone.utc).isoformat(),
        "zone_key": zone_key,
        "fold": fold,
    }

推荐至少保存三个字段：真实发生时间的 UTC 值、用户输入或展示所用的 IANA zone_key，以及在重复小时中采用的 fold。如果只是展示历史记录，可以由 UTC 和 zone key 重新计算本地时间；如果要完整还原用户当时的选择，fold 也应保留。

相关问题

zoneinfo 能自动拒绝春季不存在的时间吗？

不能把构造器当成业务校验器。要对用户输入的本地时间做 UTC 往返判断，再决定拒绝、提示修正还是采用产品约定的调整方式。

fold=0 和 fold=1 什么时候不同？

它们主要在偏移回拨造成的重复小时中对应两个不同 UTC 时刻。普通时间通常会回到同一个瞬间，缺失时间则不应直接接受任一候选。

为什么线上机器找不到 ZoneInfo？

系统可能没有 IANA 时区数据库，或运行环境没有安装第一方 tzdata。应在部署依赖中明确提供时区数据，并把 ZoneInfoNotFoundError 变成可定位的配置错误。