← 返回首页

Python 时区实测:zoneinfo 与 DST 的 6 个静默错误

Python时区夏令时

11 月 1 日凌晨,我把一台按 America/New_York 排程的服务日志导出来,发现两条记录的时间戳一模一样,可表里写着它们间隔 0 秒;再往上翻,一段本该 60 分钟的窗口变成了 120 分钟。进程没崩,单元测试全绿,监控也没告警。

问题不在日志库。它出在 datetime 的四条比较规则上,而这些规则全都写在 PEP 495 里,只是很少被写进教程。我实际在 CPython 3.13.14 + Windows 11 + tzdata 2025.2(对应 IANA 2025b)上跑了六组对照,每一组都能用十行代码复现。顺带把中国 1986 到 1991 年的夏令时也翻了出来——那六年里,「北京时间就是 UTC+8」同样不成立。

一、先分清三样东西:时区名、偏移量、夏令时

一个 ZoneInfo 对象的 key 是 IANA 名字(America/New_York),它本身不存偏移量,只存一张「什么时候切到哪个偏移」的转换表;utcoffset() 是某个具体时刻的 UTC 偏移;dst() 是这串偏移里属于夏令时的那一段。三者混着读,就会得出「纽约永远是 -5」这种结论。

Windows 上还有一层前置条件。我这台机器的 zoneinfo.TZPATH 打印出来是空元组,也就是说系统里根本没有时区数据库,全部依赖 PyPI 上的 tzdata 包。官方文档写得很直白:「Some systems, including notably Windows systems, do not have an IANA database available, and so for projects targeting cross-platform compatibility that require time zone data, it is recommended to declare a dependency on tzdata. If neither system data nor tzdata are available, all calls to ZoneInfo will raise ZoneInfoNotFoundError.」

我把 site-packages 从路径里摘掉(等价于没装 tzdata)复现了一次,连 UTC 这个 key 都拿不到:

zoneinfo._common.ZoneInfoNotFoundError: 'No time zone found with key UTC'

注意这个异常是 KeyError 的子类,所以外层写了 except KeyError 的代码会把它静默吞掉,然后继续用裸 datetime 往下跑——这是整条链上第一个「不报错」。

二、错误一:不存在的本地时刻,只会被悄悄挪走

2026 年 3 月 8 日,纽约的本地时间从 02:00 直接跳到 03:00。02:30 这个时刻当天不存在。构造它不会抛异常:

foldutcoffset换算成 UTC再反算回本地是否闭合
0-05:0007:3003:30 EDT否
1-04:0006:3001:30 EST否

两个结果都不是 02:30。fold=0 用了跳变前的偏移,落到跳变后的 03:30;fold=1 用了跳变后的偏移,落到跳变前的 01:30。官方文档对 fold 的定义正是这个:转换发生时,fold=0 取跳变前的偏移,fold=1 取跳变后的偏移——它从没承诺「这个墙钟时刻一定存在」。

判断一个墙钟时刻是不是陷阱,三行就够,而且不依赖第三方库:

def kind(w):
    d0, d1 = w.replace(fold=0), w.replace(fold=1)
    if d0.utcoffset() == d1.utcoffset():
        return "ok"
    back = d0.astimezone(UTC).astimezone(w.tzinfo)
    return "gap" if back.replace(tzinfo=None) != w.replace(tzinfo=None) else "ambiguous"

判据是「两次 fold 的偏移是否一致」;不一致时再看 fold=0 反算回来还是不是原来那个墙钟——不是就是空洞(gap),是就是重复(ambiguous)。这一条同时解决了「我怎么知道用户填的时间不存在」,比在外面套一层 try/except 靠谱得多。

三、错误二:相差一小时的两个时刻,== 认为是同一个

2026 年 11 月 1 日凌晨 2:00,纽约从 EDT 退回 EST,01:00 到 01:59 这一小时走了两遍。取 01:30,两个 fold 给出两个真实时刻:

foldutcoffset时间戳换算成 UTC
0-04:00179351100005:30
1-05:00179351460006:30

两个时刻真实相差 3600 秒。但把这两个 datetime 放进同一个表达式的后果是这样的:

也就是说,同一对对象在「按墙钟比」的世界里相等,在「按时刻比」的世界里不等,而 Python 默认给你的是前者。PEP 495 对此的原话是:「Naive and intra-zone comparisons will ignore the value of fold and return the same results as they do now. (This is the only way to preserve backward compatibility. If you need an aware intra-zone comparison that uses the fold, convert both sides to UTC first.)」括号里那句就是唯一的解法:要比真实先后,先两边都 astimezone(UTC)。

这一条会直接伪造数据。上面那台服务里,同一小时内的两条记录被集合去重成一条,报表里的请求数少了 50%,而所有断言都过——因为代码里没有一处显式比较过时间。

四、错误三:换一个 tzinfo 对象,同一个时刻反而不等

如果前一条还能靠「先转 UTC」补救,这一条更难发现:同一段代码,只要 tzinfo 不是同一个对象,结果就反过来。

我把同一个墙钟时刻 2026-11-01 01:30 配上不同的 tzinfo 对象,逐个对拍:

比较对象== 的结果
同一个 ZoneInfo 对象(缓存命中,a is b)True
ZoneInfo 与 ZoneInfo.no_cache 的同名对象False
America/New_York 与 America/TorontoFalse
两个 timezone(timedelta(hours=-4))True
两个自定义 tzinfo 实例(偏移写死 -4)True
纽约与多伦多,改到 6 月 12:00(非歧义时刻)True

纽约和多伦多这一次,两个 datetime 的墙钟相同、utcoffset() 都是 -04:00、换算成 UTC 都是 05:30——同一个真实时刻,== 却是 False。原因在 PEP 495 的一条例外:

「Whenever one or both of the operands in inter-zone comparison is such that its utcoffset() depends on the value of its fold attribute, the result is False.」

它给了形式化定义:设 toutc(t, fold) 是把 t 按给定 fold 换算成 UTC 的天真值,那么当两侧 tzinfo 不是同一个对象时,t == s 等价于 toutc(t,0) == toutc(t,1) == toutc(s,0) == toutc(s,1)。歧义小时里 toutc(t,0)=05:30、toutc(t,1)=06:30,四个值不可能同时相等,于是直接返回 False。固定偏移的 timezone 对象,utcoffset() 与 fold 无关,四个值自然一致,所以是 True。

官方文档在讲 no_cache 时也留了一句 Caution:「Using this constructor may change the semantics of your datetimes in surprising ways, only use it if you know that you need to.」这句不是客套——它改的正是相等语义本身。

于是就有了最反直觉的一幕:a != b 为真,hash(a) == hash(b) 也为真。这在 Python 里合法(要求的是「相等必同哈希」,不是反过来),但它意味着字典里能同时存在两个哈希相同的 key,任何靠哈希做的去重、分桶、缓存键都会给出两套答案。

五、错误四:加一天不是 24 小时

同一个陷阱在算术上更隐蔽。取 2026-03-07 12:00(EST,-05:00):

运算得到真实经过的秒数
加 timedelta(days=1)03-08 12:00 EDT82,800
加 timedelta(hours=24)03-08 12:00 EDT82,800
先转 UTC 加一天,再转回03-08 13:00 EDT86,400

「加一天」和「加 24 小时」在这里是完全相同的操作,因为对 aware datetime 做 timedelta 加减走的是墙钟算术,不是绝对时间。逐格看更清楚:从 03-07 22:00 起加 4 小时,墙钟落在 03-08 02:00 EST,真实只过了 14,400 秒;加 6 小时,墙钟落在 03-08 04:00 EDT,真实过了 18,000 秒;而按绝对时间加 6 小时,落在 05:00 EDT,过了 21,600 秒。三个数字,两种语义。

后果是「T+30 天到期」这类业务规则在换季那两天会差一小时,而差一小时通常还落在允差之内,于是永远不会有人发现。要做绝对时长,先 astimezone(UTC) 再加。

六、错误五:按字符串排序会把先后弄反

日志和 CSV 里最常见的做法是把 isoformat() 字符串直接排序。在同一个重复小时里,这会把顺序直接颠倒:

记录字符串时间戳
A2026-11-01T01:00:00-05:001793512800
B2026-11-01T01:30:00-04:001793511000

按字符串排,A 在前(01:00 小于 01:30);按时间戳排,B 在前——B 比 A 早 30 分钟。字符串比较在读完「01:30」这五位时已经分出胜负,压根没看后面的偏移量。

跨时区聚合时更糟。三行日志分别是上海 09:00+08:00(01:00 UTC)、UTC 08:30(08:30 UTC)、纽约 03:00-05:00(08:00 UTC),按字符串排出来的顺序是「纽约、UTC、上海」,按真实时刻排是「上海、纽约、UTC」,正好反过来。

判据只有一条:排序 key 用 timestamp(),或者先把所有值统一转到 UTC。isoformat() 适合给人看、适合给机器解析,不适合当排序键。

七、错误六:读入侧的两个静默陷阱

前五条都发生在「算」和「比」,读入侧还有两个。

第一个是 %Z。用 datetime.strptime 解析「2026-11-01 01:30 EDT」会直接抛 ValueError,因为 %Z 只认本机 time.tzname 里的缩写——我这台机器是「中国标准时间」「中国夏令时」,EDT 从来不在名单里。更麻烦的是换成本地缩写之后的结果:

datetime.strptime("2026-11-01 01:30 中国标准时间", "%Y-%m-%d %H:%M %Z")
-> datetime.datetime(2026, 11, 1, 1, 30)   # tzinfo 是 None

解析成功、不报错、时区是 None。后面接什么都会以「本地时间」的身份继续算。要用 %z(小写)拿偏移量,或者干脆按 ISO 8601 走 fromisoformat。

第二个是 fromtimestamp()。不带第二个参数时它按本机时区解释:同一个时间戳 1793511000,不传时区得到 13:30(本机 UTC+8),传 UTC 得到 05:30,传纽约得到 01:30-04:00。三行差 8 小时,都不报错。这类代码在容器里跑得好好的,搬到 UTC 时区的机器上就整体偏移——而「偏移 8 小时」在日志里长得太正常了。

顺带说清 fromisoformat 在 3.11 之后的能力边界:Z 后缀能解析,+0800 和 +08:00 都能解析,甚至连 2026-W45-5 这种 ISO 周日期也能解析成 2026-11-06。但它不接受 Z 和偏移量同时出现。

八、中国也实行过夏令时:1986 到 1991

「国内没有夏令时,所以不用管」这句话在 2026 年是对的,在 1991 年不对。用 Asia/Shanghai 往回查:

日期utcoffsetdsttzname
1985-07-01+08:000CST
1986-07-01+09:001 小时CDT
1988-05-01+09:001 小时CDT
1991-09-15+08:000CST
2026-11-01+08:000CST

遍历之后确认,Asia/Shanghai 有夏令时的年份正好是 1986 到 1991 共六年。注意 1986 年 5 月 1 日还在 CST,而 1988 年 5 月 1 日已经是 CDT——每年起始日期不同,不能拿一个日期套六年。

这对两类数据是硬伤:一是 1986 到 1991 年间的历史时间戳,按「+8 固定」换算会整整差一小时;二是「那年 7 月 1 日几点几分」这种档案类记录,跨过这六年就没法用同一个公式。2026 年的数据完全不受影响,我用同一个判据函数查过 11 月 1 日的上海 01:30,结果是 ok。

九、半小时的夏令时,和负的夏令时

还有两个边角,能反过来验证「偏移量不是常识」。

澳大利亚的 Lord Howe 岛用的是 30 分钟夏令时。2026-10-04 当地从 02:00 跳到 02:30,偏移量从 +10:30 变成 +11:00,只挪了 30 分钟。所以 02:15 是个空洞时刻:fold=0 反算回来是 02:45,fold=1 反算回来是 01:45;而 02:30 是正常的——跳变正好在它之前结束。任何「夏令时固定一小时」的假设,在这里直接崩。

爱尔兰更有意思。Europe/Dublin 的 dst() 在 1 月返回 -3600 秒,在 7 月返回 0,tzname 分别是 GMT 和 IST。也就是说这个时区把冬天标成「夏令时偏移为负」,夏天才是标准时。如果代码用「dst() 是否为 0」来判断「现在是不是夏令时」,爱尔兰全年都会答错。

十、定时任务:一年里少跑一次,多跑一次

把上面几条拼起来,就是排程问题。用同一个判据函数遍历 2026 年 365 天,按「每天 02:30 触发」和「每天 01:30 触发」各算一遍:

这不是理论。任何按本地墙钟写「每天几点」的调度器,只要所在时区有夏令时,一年里就必然出现一次少跑和一次多跑。可迁移的做法只有一种:调度器内部一律用 UTC 存下次执行时刻,展示层再转成本地时间;「每天 02:30 本地时间」这种规则,要么写成固定 UTC 偏移,要么显式接受换季那天的两种行为并在文档里写清楚。

报错实录:六段真实异常

下面六段都是我在本轮复现出来的原文,不是转述。

报错一:TypeError: can't compare offset-naive and offset-aware datetimes

原因:一侧是 fromisoformat 出来的无时区值,另一侧是 now(UTC)。解法:入库前统一规范成 aware,读出来缺时区的值按业务口径显式补 UTC 或本地,不要靠 replace 猜。

报错二:DeprecationWarning: datetime.datetime.utcnow() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.now(datetime.UTC).

原因:utcnow() 返回的是无时区的 UTC 值,语义上最容易被当成「带时区」。解法:换成 datetime.now(datetime.UTC);这条警告只在 warnings 过滤器打开时才看得见,默认会被吞掉。

报错三:ValueError: Invalid isoformat string: '2026-11-06T06:10:00.123456+08:00Z'

原因:Z 与 +08:00 同时出现,属于两种互斥写法。解法:解析前先剥掉 Z,或统一成 +00:00。

报错四:zoneinfo._common.ZoneInfoNotFoundError: 'No time zone found with key America/New York'

原因:key 里写了空格。注意异常信息会把你写错的 key 原样回显,看着像「库里没有美国时区」。解法:key 必须是 IANA 规范名,含下划线;上线前用 available_timezones() 校验一遍。

报错五:ValueError: offset must be a timedelta strictly between -timedelta(hours=24) and timedelta(hours=24), not datetime.timedelta(days=1, seconds=3600).

原因:手写 timezone(timedelta(hours=25))。解法:固定偏移只用来表达 UTC 与本地的差值,跨 24 小时的「时区」不存在,改用 ZoneInfo。

报错六:ValueError: time data '2026-11-01 01:30 EDT' does not match format '%Y-%m-%d %H:%M %Z'

原因:%Z 只匹配本机 time.tzname。解法:改用 %z 或 fromisoformat;如果数据源只能给缩写,就自己维护一张缩写到偏移的映射表,别指望 strptime。

上线前照着走一遍

这六条我压成了六个判据,都可以写成断言:

1. 所有 datetime 要么都是 aware,要么都是 naive,混用视为缺陷——用 d.tzinfo is None 逐个查。

2. 跨时区比较、排序、去重之前,统一 astimezone(UTC);不要依赖 == 和集合。

3. 需要「真实经过时长」时先转 UTC 再加 timedelta;需要「本地日历日」时才用墙钟算术,并在注释里写明。

4. 任何来自用户或外部系统的墙钟时间,进库前跑一次上面那个 kind() 判据,gap 与 ambiguous 分别按业务规则处置。

5. 调度器内部用 UTC,展示层转本地;「每天几点」的规则必须写明换季行为。

6. 时间字段的序列化格式固定一种(建议带偏移的 ISO 8601),排序键一律用时间戳。

最后一句实话:这些坑没有一个是 Python 特有的。Java 的 ZonedDateTime、JS 的 Date、Go 的 time 各有各的版本,但「本地时间是一张映射表,不是一个坐标」这条前提完全一样。真正省事的做法不是背下六条规则,而是把「时间一律存 UTC、比较一律转 UTC、只有给人看的时候才转本地」当成默认值。

关于本站:本文不含任何联盟推广链接,文中数字全部来自本机 2026 年 11 月 6 日的实测与 PEP 495、zoneinfo 官方文档原文。上一轮我在 Python json 序列化 里踩过「无时区 datetime 不带偏移量」的同源坑,两篇可以对着看;如果你正在写定时任务,huey / APScheduler / Celery 三选一 那篇讲了调度层的失配,重试与幂等 那篇讲了重跑的时间窗问题。

👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务

👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页