Python 处理日期时间要注意什么？naive 和 aware 有什么区别？

简化版

Python 的 datetime 分两种：不带时区信息的 naive（tzinfo is None）和带时区信息的 aware。两者不能互相比较、不能相减，混用会直接抛 TypeError: can't subtract offset-naive and offset-aware datetimes——这是日期时间领域最常见的一类线上事故。正确姿势是「内部一律用 aware 的 UTC 时间，只在展示给用户时才转成本地时区」：取当前时间用 datetime.now(timezone.utc)（不要用已在 3.12 弃用的 datetime.utcnow()——它返回的是「UTC 的时间数值但 tzinfo=None」的 naive 对象，是无数 bug 的源头）；时区数据用标准库 zoneinfo（3.9+）：ZoneInfo("Asia/Shanghai")，直接 dt.astimezone(ZoneInfo("Asia/Shanghai")) 转换即可。几个必须知道的坑：① timedelta(days=1) 是「精确 24 小时」而不是「日历上的第二天」，在有夏令时的时区里两者会差一小时；② 跨夏令时做加减必须「转成 UTC 算完再转回来」；③ 用 pytz 的老代码必须配合 localize()，直接 datetime(..., tzinfo=pytz.timezone(...)) 会得到诡异的 LMT 偏移（如 +8:06）；④ 存数据库/传接口一律用 UTC 或带偏移量的 ISO 8601 字符串。核心记忆：存 UTC、算 UTC、只在显示时转本地；utcnow() 已废弃，用 now(timezone.utc)。

详细版

naive vs aware 对照：

维度	naive（`tzinfo is None`）	aware（有 `tzinfo`）
含义	「7 点」但不知道是哪儿的 7 点	明确的时间点（全球唯一）
相减	只能和 naive 相减	只能和 aware 相减
比较	和 aware 比较抛 `TypeError`	——
时间戳	`timestamp()` 按本机时区解释（隐患）	准确
来源	`now()`、`utcnow()`、`strptime()`	`now(tz)`、`astimezone()`、`fromisoformat` 带偏移
用途	「本地挂钟时间」「生日」等无时区语义的场合	其余所有场合

from datetime import datetime, timezone, timedelta
from zoneinfo import ZoneInfo          # Python 3.9+ 标准库

SH = ZoneInfo("Asia/Shanghai")
NY = ZoneInfo("America/New_York")

# ① 取当前时间：只有一种正确写法
now_utc = datetime.now(timezone.utc)          # ✓ aware，UTC
# now_bad = datetime.utcnow()                 # ✗ 3.12 起弃用：UTC 的数值 + tzinfo=None（naive！）
now_local = datetime.now(SH)                  # ✓ aware，上海时间（需要给用户看时才用）

# ② naive 和 aware 不能混用
naive = datetime(2026, 7, 31, 12, 0)
# naive - now_utc                              # ✗ TypeError
# naive < now_utc                              # ✗ TypeError

# ③ 给 naive 补上时区 vs 把 aware 换算到另一个时区（两个完全不同的操作）
aware_sh = naive.replace(tzinfo=SH)           # 「这个挂钟时间是上海的」— 数值不变、只贴标签
in_ny    = aware_sh.astimezone(NY)            # 「同一时刻在纽约是几点」— 数值会变
print(aware_sh)   # 2026-07-31 12:00:00+08:00
print(in_ny)      # 2026-07-31 00:00:00-04:00

# ④ 夏令时：timedelta(days=1) 不等于"日历第二天"
d = datetime(2026, 3, 7, 12, 0, tzinfo=NY)    # 美国 3/8 凌晨切夏令时
print(d + timedelta(days=1))                  # 2026-03-08 12:00:00-04:00  ← 挂钟仍是 12 点
print((d + timedelta(days=1)) - d)            # 1 day, 0:00:00 ← 但实际只过了 23 小时！

# ✓ 要"精确 24 小时之后"：转 UTC 算完再转回来
exact_24h = (d.astimezone(timezone.utc) + timedelta(days=1)).astimezone(NY)
print(exact_24h)                              # 2026-03-08 13:00:00-04:00

# ⑤ 解析与格式化
s = "2026-07-31T12:00:00+08:00"
dt = datetime.fromisoformat(s)                # ✓ 3.7+ 能解析偏移；3.11+ 支持 'Z' 结尾
print(dt.isoformat())                         # 2026-07-31T12:00:00+08:00
print(dt.strftime("%Y-%m-%d %H:%M"))          # 2026-07-31 12:00（strftime 不带时区信息！）

# ⑥ 时间戳互转（时间戳永远是 UTC 语义，没有时区概念）
ts = dt.timestamp()                           # aware → 准确
print(datetime.fromtimestamp(ts, tz=SH))      # ✓ 显式给 tz
# print(datetime.fromtimestamp(ts))           # ⚠️ 不给 tz → 按★本机时区★返回 naive

# ⑦ 只做日期计算用 date；只做耗时测量用 perf_counter（不受系统时间调整影响）
import time
t0 = time.perf_counter(); ...; elapsed = time.perf_counter() - t0     # ✓ 单调时钟

⚠️ 两个最致命的坑：① datetime.utcnow() 返回的是 naive 对象——它的数值是 UTC 时间，但 tzinfo 是 None，于是这个对象「看起来像 UTC、行为却像本地时间」：拿它调用 .timestamp() 时 Python 会按本机时区去解释它，在东八区服务器上直接算错 8 小时；和 aware 对象比较又会抛 TypeError。Python 3.12 已正式弃用 utcnow() 和 utcfromtimestamp()，唯一正确的写法是 datetime.now(timezone.utc)。② replace(tzinfo=...) 和 astimezone(...) 是完全不同的两个操作：replace 只是「贴标签」——挂钟数值一点不动，用于给 naive 补上它本来就属于的时区；astimezone 是「换算」——把同一个时刻表示成另一个时区的挂钟数值。对一个已经 aware 的对象用 replace(tzinfo=X) 等于强行改写它代表的时刻（凭空平移几小时），是常见的数据污染源。此外用老库 pytz 时绝不能写 datetime(2026,1,1, tzinfo=pytz.timezone("Asia/Shanghai"))——会得到 1900 年前的 LMT 偏移 +08:06，必须用 tz.localize(naive_dt)；新代码直接用标准库 zoneinfo 就没这个问题。

完整版教学

一、naive 与 aware：为什么必须分清

naive（tzinfo is None）：只有"挂钟读数"，不知道是哪个时区的
  datetime(2026, 7, 31, 12, 0)
  → 这是北京的 12 点？伦敦的 12 点？信息缺失，无法确定是"哪个时刻"

aware（有 tzinfo）：全球唯一确定的时刻
  datetime(2026, 7, 31, 12, 0, tzinfo=ZoneInfo("Asia/Shanghai"))
  → 等价于 UTC 的 04:00，等价于纽约的前一天 00:00

混用会怎样：
  naive - aware      → TypeError: can't subtract offset-naive and offset-aware
  naive < aware      → TypeError
  naive == aware     → ★不报错，永远返回 False★（== 被特意设计成不抛异常）
  → 最阴险的是 == ：if a == b 静默为假，逻辑走错分支且毫无提示

naive 的隐藏危险：timestamp() 会按★本机时区★解释它
  naive = datetime(2026, 7, 31, 12, 0)
  naive.timestamp()
  在东八区机器上  → 解释为北京 12:00 → 1785...（对应 UTC 04:00）
  在 UTC 机器上   → 解释为 UTC  12:00 → 相差 28800 秒（8 小时）
  ★同一份代码、同一个值，在开发机和服务器上算出不同结果★
  → 这就是"本地能跑、上线差 8 小时"类 bug 的根源

什么时候 naive 才是对的：
  ① 真正没有时区语义的：生日、纪念日、"每天 9 点提醒"（挂钟语义）
  ② 数据库里已约定"全部存 UTC"且代码边界处立刻补上 tzinfo
  除此之外：一律用 aware

naive 和 aware 的区别不是「带不带一个属性」，而是**「它到底是不是一个确定的时刻」：datetime(2026,7,31,12,0) 这个 naive 对象只是「某地的 12 点」，你无法判断它和另一个时间谁先谁后；而 aware 对象对应地球上唯一的一瞬间。Python 的策略是拒绝混算**（相减、比较大小都抛 TypeError），但有个例外要特别小心：== 不抛异常，而是永远返回 False——于是 if a == b: 静默走错分支，比直接报错难查得多。naive 更深的危险在于 timestamp() 会按运行机器的本地时区来解释它，同一份代码在开发机（东八区）和服务器（UTC）上会算出相差 8 小时的结果——大量「本地测试正常、上线时间全错」的事故都来自这里。

二、时区数据从哪来：zoneinfo vs pytz

Python 3.9+ 标准库 zoneinfo（首选）：
  from zoneinfo import ZoneInfo
  ZoneInfo("Asia/Shanghai")      # IANA 时区数据库的名字
  ★ Windows 上系统自带时区库可能缺失 → pip install tzdata（纯数据包）

用法直观、没有历史包袱：
  dt = datetime(2026, 7, 31, 12, 0, tzinfo=ZoneInfo("Asia/Shanghai"))   ✓ 直接传就对
  dt.astimezone(ZoneInfo("America/New_York"))                            ✓

老库 pytz 的经典陷阱（遗留项目里到处都是）：
  ✗ datetime(2026, 7, 31, 12, 0, tzinfo=pytz.timezone("Asia/Shanghai"))
    → 得到 +08:06 的偏移！（LMT，上海 1900 年前的"地方平太阳时"）
    → 因为 pytz 的 tzinfo 对象携带的是"某一段历史时期的偏移"，
      直接塞进构造函数会取到列表里的第一条（最古老的那条）
  ✓ pytz 必须这样用：
    tz = pytz.timezone("Asia/Shanghai")
    dt = tz.localize(datetime(2026, 7, 31, 12, 0))      # 给 naive 加时区
    dt2 = dt.astimezone(pytz.utc)                        # 换算
    ★ 做完加减法后还要 tz.normalize(dt) 修正夏令时
  → 结论：新代码一律用 zoneinfo；pytz 只在维护老项目时才碰

固定偏移的写法（不需要完整时区规则时）：
  timezone.utc                       # UTC
  timezone(timedelta(hours=8))       # 固定 +08:00（★没有夏令时规则★）
  ★ 中国不实行夏令时，用固定 +08:00 通常没问题；
    但欧美时区绝不能用固定偏移代替 ZoneInfo，否则夏令时期间全错一小时

常用时区名（IANA 格式：地区/城市）：
  Asia/Shanghai（中国大陆统一用这个）、Asia/Tokyo、Europe/London、
  America/New_York、UTC
  ✗ 不要用 "CST"（歧义：中国标准时 / 美国中部时 / 古巴标准时都叫 CST）

时区数据只有一个正确来源：IANA 时区数据库（记录了全世界每个地区历史上所有的时区规则和夏令时变更）。Python 3.9 起把它变成了标准库 zoneinfo，用法直观——直接 tzinfo=ZoneInfo("Asia/Shanghai") 就是对的（Windows 上如果报找不到时区，pip install tzdata 装上纯数据包即可）。而遗留项目里大量使用的 pytz 有一个著名陷阱：它的 tzinfo 对象携带的是「某一段历史时期的偏移」，直接塞进 datetime(...) 构造函数会拿到列表里最古老的那条——上海会得到 +08:06 的 LMT（1900 年前的地方平太阳时），算出来的时间差 6 分钟，非常隐蔽。pytz 的正确用法是 tz.localize(naive_dt)，加减之后还要 tz.normalize()。另外注意：固定偏移 timezone(timedelta(hours=8)) 没有夏令时规则，中国不实行夏令时用它没问题，但欧美时区必须用 ZoneInfo；时区名要用 IANA 的「地区/城市」格式，别用 CST 这种缩写（中国标准时、美国中部时、古巴标准时都叫 CST）。

三、utcnow() 为什么是陷阱

三个"取当前时间"的函数，只有一个是对的：

  datetime.now()               → naive，本机时区的挂钟读数
  datetime.utcnow()            → naive，UTC 的挂钟读数   ★★最危险★★
  datetime.now(timezone.utc)   → aware，UTC              ✓ 唯一推荐

为什么 utcnow() 最危险：它是"UTC 的数值 + 没有时区标签"
  u = datetime.utcnow()        # 假设此刻北京时间 20:00 → u = 12:00，tzinfo=None
  u.timestamp()                # Python 把 naive 按★本机时区★解释
                               # → 认为这是"北京的 12:00" → 算出的时间戳晚了 8 小时
  u.astimezone(SH)             # 同样按本机时区解释后再转 → 结果错上加错
  u == datetime.now(timezone.utc)   # False（naive 与 aware 比较恒为 False）

  → 它"看起来是 UTC，行为却是本地时间"，是最典型的"沉默的错误"

Python 3.12 起：
  DeprecationWarning: datetime.utcnow() is deprecated
  DeprecationWarning: datetime.utcfromtimestamp() is deprecated
  官方替代：datetime.now(timezone.utc) / datetime.fromtimestamp(ts, timezone.utc)

对照速查：
  ┌────────────────────────────┬────────────────────────────────┐
  │ 弃用写法                    │ 正确写法                        │
  ├────────────────────────────┼────────────────────────────────┤
  │ datetime.utcnow()          │ datetime.now(timezone.utc)     │
  │ datetime.utcfromtimestamp(t)│ datetime.fromtimestamp(t, timezone.utc)│
  │ datetime.fromtimestamp(t)  │ datetime.fromtimestamp(t, tz)  │（显式给 tz）
  │ dt.replace(tzinfo=utc)（对已 aware 的）│ dt.astimezone(utc)  │
  └────────────────────────────┴────────────────────────────────┘

顺带：三种"时间"用途别混
  datetime.now(tz)      墙上时钟（会被 NTP 校时、用户改系统时间影响）→ 记录"何时发生"
  time.perf_counter()   单调时钟（不受校时影响）→ ★测耗时必须用它★
  time.monotonic()      单调时钟（进程间可比）→ 超时判断

utcnow() 是 Python 时间处理里最著名的坑，值得单独讲：它返回的对象数值是 UTC、tzinfo 却是 None，形成了「看起来是 UTC、行为却是本地时间」的分裂状态。一旦对它调用 .timestamp() 或 .astimezone()，Python 会按运行机器的本地时区去解释这个数值——在东八区服务器上直接错 8 小时，而且不报任何错。它和 aware 对象比较又恒为 False。正因为这种「沉默的错误」太多，Python 3.12 正式弃用了 utcnow() 和 utcfromtimestamp()，标准答案统一为 datetime.now(timezone.utc) 和 datetime.fromtimestamp(ts, timezone.utc)。顺带记住另一个分工：测量耗时绝不能用 datetime.now() 相减——墙上时钟会被 NTP 校时或用户改系统时间影响，甚至可能出现负数耗时，测耗时要用 time.perf_counter() 这类单调时钟。

四、存储与传输：统一用 UTC

黄金法则：★存 UTC、算 UTC、只在展示层转本地★

  用户输入(带时区) ──→ 转成 UTC ──→ 业务计算/存储/比较 ──→ 展示时 astimezone(用户时区)
                     ↑                                   ↑
                   入口转一次                          出口转一次

为什么不能"存本地时间"：
  ① 服务器迁移/多地部署 → 同一列里混着不同时区的值，无法比较排序
  ② 夏令时切换时本地时间会★重复一小时★（凌晨 1:30 一天出现两次）→ 数据无法区分
  ③ 时区规则会变（各国经常调整夏令时政策），存本地时间意味着历史数据的含义会变

数据库怎么存：
  PostgreSQL: timestamptz（存 UTC，读写自动按会话时区转换）✓ 首选
  MySQL:      DATETIME 不带时区 → ★约定存 UTC★，代码里读出后立刻 replace(tzinfo=utc)
              TIMESTAMP 会按会话时区自动转换（且有 2038 年上限）→ 容易踩坑
  存整数时间戳：跨语言最省事，但可读性差、无法直接用 SQL 做日期函数

接口怎么传：
  ✓ ISO 8601 带偏移量："2026-07-31T12:00:00+08:00" 或 "2026-07-31T04:00:00Z"
  ✓ Unix 时间戳（整数秒或毫秒，天然是 UTC 语义）
  ✗ "2026-07-31 12:00:00"（不带时区，接收方只能猜）
  ✗ 依赖服务器本地时区的格式化输出

解析与生成：
  datetime.fromisoformat("2026-07-31T12:00:00+08:00")   ✓ 3.7+
  datetime.fromisoformat("2026-07-31T04:00:00Z")        ✓ ★3.11+ 才支持 Z★
  dt.isoformat()                                        ✓ 生成标准格式
  ★ strftime("%Y-%m-%d %H:%M:%S") 会丢掉时区信息 → 只用于给人看的展示

一个完整例子：
  raw = "2026-07-31T12:00:00+08:00"
  dt_utc = datetime.fromisoformat(raw).astimezone(timezone.utc)   # 入口转 UTC
  save(dt_utc)                                                     # 存 UTC
  # ...读出后展示给上海用户
  show = dt_utc.astimezone(ZoneInfo("Asia/Shanghai")).strftime("%Y-%m-%d %H:%M")

工程上唯一可靠的架构是「沙漏模型」：入口把一切转成 UTC、内部全程 UTC、只在展示层转成用户时区。存本地时间之所以是灾难，有三个硬理由：服务器迁移或多地部署后同一列里混着不同时区的值、夏令时回拨时本地时间会重复一小时（凌晨 1:30 一天出现两次，数据无法区分先后）、以及时区规则本身会变（各国经常调整夏令时政策，存本地时间意味着历史数据的含义会随之改变）。数据库层面 PostgreSQL 的 timestamptz 是最省心的；MySQL 的 DATETIME 不带时区，就必须团队约定「这一列存 UTC」并在读出后立刻 replace(tzinfo=timezone.utc) 补上标签。接口传输一律用带偏移量的 ISO 8601 或整数时间戳，fromisoformat 是标准解析方式（注意 Z 结尾的写法要 3.11+ 才支持），而 strftime 输出会丢时区信息，只适合给人看。

五、日期算术的陷阱：夏令时与「日历天」

陷阱 1：timedelta(days=1) 是"精确 24 小时"，不是"日历第二天"
  在无夏令时的时区（如中国）：两者恰好一致，看不出问题
  在有夏令时的时区：
    d = datetime(2026, 3, 7, 12, 0, tzinfo=ZoneInfo("America/New_York"))
    d + timedelta(days=1)   → 3/8 12:00（★挂钟还是 12 点，实际只过了 23 小时★）
    → Python 的规则：aware datetime 做加减时，先按"挂钟"算，再重新解释偏移

  想要"精确 24 小时"：转 UTC 再算
    (d.astimezone(timezone.utc) + timedelta(days=1)).astimezone(NY)   → 3/8 13:00
  想要"日历第二天的同一时刻"：直接 timedelta(days=1)（Python 默认行为就对）

陷阱 2：夏令时切换造成的"不存在"和"重复"的时间
  美国 2026-03-08 02:00 → 直接跳到 03:00
    datetime(2026, 3, 8, 2, 30, tzinfo=NY)   ← 这个挂钟时间★根本不存在★
    Python 不报错，会给出一个"折中"的偏移 → 结果可能不是你想要的
  美国 2026-11-01 01:30 → 一天出现★两次★（一次 EDT、一次 EST）
    用 fold=0 / fold=1 区分：
    datetime(2026, 11, 1, 1, 30, tzinfo=NY, fold=0)   # 第一次（夏令时 EDT）
    datetime(2026, 11, 1, 1, 30, tzinfo=NY, fold=1)   # 第二次（标准时 EST）
    ★ 这两个对象的 utcoffset() 相差 1 小时，timestamp() 也不同

陷阱 3：月/年的加减标准库不支持
  timedelta 只有 days/seconds/... ★没有 months/years★（因为月长不固定）
  d + timedelta(days=30)     ≠ "下个月同一天"
  ✓ 用 dateutil.relativedelta：d + relativedelta(months=1)
    （它还会自动处理 1/31 + 1 个月 = 2/28 这种边界）
  ✓ 或自己算：calendar.monthrange(y, m)[1] 拿到该月天数

陷阱 4：比较"同一天"要小心时区
  两个 aware 对象即使 date() 不同，也可能是同一时刻的不同表示
  ✓ 判断"是不是同一天"：先统一 astimezone(目标时区) 再取 .date()

安全的算术清单：
  两个 aware 相减        ✓ 得到精确的 timedelta（自动处理时区）
  加减小时/分钟/秒       ⚠ 跨 DST 时先转 UTC
  加减天数（日历语义）    ✓ 直接 timedelta(days=n)
  加减月/年             ✗ 用 dateutil.relativedelta
  排序/比较             ✓ aware 之间随便比（内部按 UTC 时刻）

日期算术的坑几乎全部来自夏令时。核心机制要理解：aware datetime 做 + timedelta 时，Python 先按「挂钟数值」加，再重新解释该时刻的偏移——所以 d + timedelta(days=1) 得到的是「日历上的第二天同一挂钟时间」，跨过夏令时切换时实际只流逝了 23 小时（或 25 小时）。两种需求要分清：要日历语义（明天这个点开会）直接用 timedelta(days=1) 就对；要物理时长语义（24 小时后过期）必须转成 UTC 算完再转回来。另外夏令时会制造两类畸形时刻：切换那天有根本不存在的挂钟时间（凌晨 2:30 被跳过），也有重复出现两次的时间（回拨那天的 1:30），后者用 fold=0/1 区分。最后记住 timedelta 没有 months 和 years（月长不固定，标准库拒绝猜），需要「下个月同一天」得用 dateutil.relativedelta（它还会把 1/31 加一个月正确处理成 2/28）。

六、常用任务速查与选型

① 取当前时间
   datetime.now(timezone.utc)                    # 存储/计算
   datetime.now(ZoneInfo("Asia/Shanghai"))       # 直接给用户看

② naive ⇄ aware
   naive → aware（这个挂钟属于某时区）：dt.replace(tzinfo=ZoneInfo("Asia/Shanghai"))
   aware → 另一个时区（同一时刻换算）：dt.astimezone(ZoneInfo("America/New_York"))
   aware → naive（丢弃时区，慎用）：    dt.replace(tzinfo=None)
   ★ 一句话记：replace 贴标签（数值不变）、astimezone 做换算（数值会变）

③ 与时间戳互转
   dt.timestamp()                                # aware → float 秒
   datetime.fromtimestamp(ts, timezone.utc)      # → aware（★永远显式给 tz★）

④ 字符串
   datetime.fromisoformat("2026-07-31T12:00:00+08:00")     # 解析（首选）
   datetime.strptime("31/07/2026", "%d/%m/%Y")             # 自定义格式（返回 naive！）
   dt.isoformat() / dt.strftime("%Y-%m-%d %H:%M")          # 生成

⑤ 常用计算
   (a - b).total_seconds()          # 两个时刻相差多少秒（★别用 .seconds★，它只是"不满一天的部分"）
   dt.date() / dt.time()            # 取日期/时间部分
   dt.weekday()                     # 周一=0 …… 周日=6（isoweekday() 是 1~7）
   dt.replace(hour=0, minute=0, second=0, microsecond=0)   # 当天零点

⑥ 三类"时钟"选型
   datetime.now(tz)        记录"何时发生"（可能被校时/改系统时间影响）
   time.perf_counter()     ★测耗时★（单调、高精度、只用于差值）
   time.monotonic()        超时/心跳判断（单调）

⑦ 第三方库何时上
   标准库够用：zoneinfo（3.9+）已覆盖 95% 需求
   dateutil：  月/年加减（relativedelta）、模糊字符串解析（parser.parse）
   pendulum / arrow：想要更顺手的链式 API 时（但会引入依赖，团队要统一）

★ 最容易被扣分的细节：(a-b).seconds vs total_seconds()
  相差 25 小时时：.days=1、.seconds=3600、.total_seconds()=90000.0
  用 .seconds 会得到 3600（"1 小时"）→ 严重错误

日常任务按这张表办即可，但有几个细节最容易被面试官抓：replace 与 astimezone 的分工（贴标签 vs 换算）、fromtimestamp 必须显式给 tz（否则按本机时区返回 naive）、以及 timedelta.seconds 和 total_seconds() 的天壤之别——.seconds 只是「不满一天的那部分秒数」，两个相差 25 小时的时刻算出来是 3600（一小时），而 total_seconds() 才是 90000.0，用错了就是数量级的错误。选型上，zoneinfo 进标准库之后已经覆盖 95% 的需求，只有「加减月/年」和「模糊解析用户输入的日期字符串」才真正需要 dateutil；pendulum、arrow 这类库提供更顺手的链式 API，但引入依赖前要让团队统一，否则项目里三种时间对象混用会更糟。

记忆钩子：「日期时间只需守住一句话：★存 UTC、算 UTC、只在展示时转本地★（沙漏模型：入口转一次、出口转一次）。★三条铁律：一是取当前时间只写 datetime.now(timezone.utc)——utcnow() 返回『UTC 数值 + tzinfo=None』的 naive 对象，看着像 UTC、行为像本地时间，调 .timestamp() 时按本机时区解释、东八区直接错 8 小时，Python 3.12 已弃用；二是 replace(tzinfo=X) 是贴标签（数值不动，用于给 naive 补时区）、astimezone(X) 是换算（数值改变，用于 aware 换时区），对已 aware 的对象 replace 等于凭空平移时刻；三是 naive 和 aware 不能相减比较（抛 TypeError），但 == 恒为 False 不报错——这是最阴险的静默 bug。★夏令时三坑：timedelta(days=1) 是『日历第二天』不是『精确 24 小时』（要精确时长就转 UTC 算完再转回）、切换日有根本不存在的挂钟时间、回拨日有重复两次的时间（用 fold=0/1 区分）。★还有：timedelta 没有 months/years（用 dateutil.relativedelta）、(a-b).seconds 只是不满一天的部分（要用 total_seconds()）、测耗时用 time.perf_counter() 而不是 datetime、pytz 必须 tz.localize()（直接塞构造函数会得到 +08:06 的 LMT）、新代码一律用标准库 zoneinfo。」

七、常见误区与追问

误区：datetime.utcnow() 返回的是 UTC 时间，可以直接用来存储和比较。 它返回的是 naive 对象——数值是 UTC，但 tzinfo 是 None，形成「看起来是 UTC、行为却是本地时间」的分裂状态。对它调用 .timestamp() 或 .astimezone() 时，Python 会按运行机器的本地时区去解释这个数值，东八区服务器上直接算错 8 小时且不报错；和 aware 对象比较又恒为 False。Python 3.12 已正式弃用 utcnow() 和 utcfromtimestamp()，唯一正确写法是 datetime.now(timezone.utc) 和 datetime.fromtimestamp(ts, timezone.utc)。老代码里满屏的 utcnow() 是时间类 bug 的第一大来源，值得专门排查替换。
误区：replace(tzinfo=X) 和 astimezone(X) 差不多，都是设置时区。 完全不同。replace(tzinfo=X) 是贴标签：挂钟数值一点不改，只是声明「这个读数属于 X 时区」，正确用途是给一个本来就属于 X 时区的 naive 对象补上时区信息（比如从只存 UTC 的 MySQL 列读出来后 replace(tzinfo=timezone.utc)）。astimezone(X) 是换算：保持「时刻」不变，把它表示成 X 时区的挂钟读数，数值会变。对一个已经 aware 的对象用 replace(tzinfo=X) 等于凭空把它代表的时刻平移了几个小时，是很隐蔽的数据污染——比如把 UTC 的 12:00 replace 成上海时区，得到的是「上海 12:00」（即 UTC 04:00），凭空提前了 8 小时。
误区：naive 和 aware 混用一定会报错，所以不会静默出错。 相减和比较大小确实抛 TypeError，但 == 被特意设计成不抛异常、而是永远返回 False（!= 恒为 True）。于是 if 记录时间 == 目标时间: 这样的判断会静默走错分支，缓存永不命中、去重永远失效、定时任务永远不触发——都不报错，只是「行为不对」。同理 in 判断（内部用 ==）、字典查找、set 去重也全部受影响。所以不能靠「反正会报错」来兜底，必须在数据入口处就统一成 aware UTC。
误区：timedelta(days=1) 就是 24 小时之后。 对 aware datetime 来说，Python 的加法是按挂钟数值算、再重新解释偏移，所以 d + timedelta(days=1) 得到的是「日历上的第二天、同一个挂钟时间」。在跨夏令时切换的那一天，这实际只流逝了 23 小时（春季前跳）或 25 小时（秋季回拨）。两种语义要分清：要日历语义（明天这个点开会）就直接用 timedelta(days=1)（默认行为正是你要的）；要物理时长语义（24 小时后过期、令牌有效期）必须转成 UTC 计算完再转回来。中国不实行夏令时，所以这个坑在纯国内业务里不会暴露，一旦做海外业务就会集中爆发。
误区：(a - b).seconds 就是两个时间相差的秒数。 timedelta 把差值拆成 days、seconds、microseconds 三部分，.seconds 只是「不满一天的那部分」，取值范围是 0~86399。两个相差 25 小时的时刻，.days 是 1、.seconds 是 3600——直接用 .seconds 会得出「相差 1 小时」的荒谬结论。正确的是 .total_seconds()（返回 float，包含全部天数）。同类陷阱还有负的时间差：timedelta(-1) 的 .days 是 -1、.seconds 是 0，但 timedelta(hours=-1) 的 .days 是 -1、.seconds 是 82800——直接看这两个字段极易误判方向，一律用 total_seconds() 最安全。
追问：为什么必须存 UTC 而不是本地时间？ 三个硬理由。① 可比较性：服务器可能迁移或多地部署，本地时间存进同一列后混着不同时区的值，排序和区间查询全部失效。② 夏令时的重复与缺失：回拨那天本地时间的 1:00~2:00 会出现两次，存下来的 01:30 无法区分是第一次还是第二次（这在计费、日志排序、幂等判断上是真实事故）；前跳那天则有一段本地时间根本不存在。③ 时区规则会变：各国经常调整夏令时政策甚至标准偏移，UTC 是绝对基准而本地时间的含义会随规则修订而漂移，历史数据会「变意思」。UTC 没有夏令时、全球唯一、单调递增，是唯一适合做存储和计算基准的表示。展示层再 astimezone(用户时区) 转换即可，成本极低。
追问：zoneinfo 和 pytz 到底差在哪，为什么老代码里到处是 localize()？ pytz 早于 PEP 495（fold 属性）出现，当时的 tzinfo 接口无法表达「同一个挂钟时间在夏令时前后有两种偏移」，于是 pytz 采取了变通方案：它的 timezone("Asia/Shanghai") 返回的对象携带的是某一段历史时期的固定偏移，其中默认（第一条）往往是 1900 年前的 LMT（地方平太阳时）——所以直接 datetime(2026,1,1, tzinfo=pytz.timezone("Asia/Shanghai")) 会得到诡异的 +08:06。正确用法是 tz.localize(naive_dt)（让 pytz 根据具体日期挑选正确的偏移对象），做完加减还要 tz.normalize(dt) 重新修正。而 Python 3.9 的 zoneinfo 基于 PEP 495，ZoneInfo 对象是「有状态感知」的：同一个对象在不同日期会给出不同的偏移，因此可以直接写 tzinfo=ZoneInfo(...)，不需要 localize/normalize，歧义时刻用 fold=0/1 区分。新代码一律用 zoneinfo（Windows 上装 tzdata 包提供数据）。
追问：测量一段代码的耗时，为什么不能用 datetime.now() 相减？ 因为 datetime.now() 读的是墙上时钟（wall clock），它会被 NTP 校时、管理员手动改系统时间、以及夏令时调整影响——测量期间只要发生一次校时，算出来的耗时就会凭空多出或少掉几秒，甚至出现负数耗时（在容器和虚拟机里 NTP 跳变并不罕见）。正确做法是用单调时钟：time.perf_counter() 提供进程内最高精度且保证单调递增的计时器，专门用于测量时间差（它的绝对值没有意义，只能相减）；time.monotonic() 同样单调，适合做超时和心跳判断。反过来，「这件事发生在什么时刻」必须用 datetime.now(timezone.utc)——单调时钟没有日历意义。两类时钟各司其职，混用就会出错。

八、加强记忆

日期时间处理只需守住一句话：存 UTC、算 UTC、只在展示时转本地（沙漏模型——入口把一切转成 aware UTC，内部全程 UTC，出口 astimezone(用户时区)）。第一层是 naive 与 aware 的区别：naive（tzinfo is None）只是「某地的挂钟读数」、不代表确定时刻，timestamp() 会按运行机器的本地时区去解释它（同一份代码在开发机和 UTC 服务器上差 8 小时）；aware 才是全球唯一的时刻。两者相减比较抛 TypeError，但 == 恒为 False 且不报错——缓存不命中、去重失效这类静默 bug 都源于此。第二层是三条 API 铁律：① 取当前时间只写 datetime.now(timezone.utc)，utcnow() 返回的是「UTC 数值 + tzinfo=None」的 naive 对象，3.12 已弃用；② replace(tzinfo=X) 是贴标签（数值不动，给 naive 补时区）、astimezone(X) 是换算（数值改变），对已 aware 的对象 replace 等于凭空平移时刻；③ fromtimestamp(ts) 必须显式传 tz，否则按本机时区返回 naive。第三层是夏令时三坑：timedelta(days=1) 是「日历第二天」而非「精确 24 小时」（要物理时长就转 UTC 算完再转回）、切换日存在根本不存在的挂钟时间、回拨日存在重复两次的时间（用 fold=0/1 区分）。其余高频细节：timedelta 没有 months/years（用 dateutil.relativedelta）；(a-b).seconds 只是「不满一天的部分」，必须用 total_seconds()；测耗时用 time.perf_counter() 而不是 datetime（墙上时钟会被校时影响甚至出现负值）；时区数据用标准库 zoneinfo（3.9+），老库 pytz 必须 tz.localize()（直接塞进构造函数会拿到 +08:06 的 LMT）；接口传输用带偏移量的 ISO 8601（fromisoformat 解析，Z 结尾需 3.11+），时区名用 IANA 的「地区/城市」格式而不是有歧义的 CST。

简化版

详细版