PyMongo 4 强制要求写入的 datetime 必须是 timezone-aware，否则抛出 TypeError；读取时统一还原为 UTC；解析字符串需确保时区信息，聚合结果的时间字段也需手动设 tzinfo。
PyMongo 4 默认不支持 naive datetime 写入
PyMongo 4 强制要求写入 MongoDB 的 datetime 对象必须是 timezone-aware（带时区），否则会直接抛出 TypeError: tzinfo must be specified。这不是配置问题，而是驱动层的硬性校验——哪怕你用 datetime.now() 或 datetime.utcnow()，只要没显式绑定 tzinfo，就会失败。
常见错误现象：
– 插入文档时报错 TypeError: tzinfo must be specified
– 使用 pendulum.now() 或 arrow.now() 却仍报错（它们默认返回 aware，但若误调了 .naive 或用了 .replace(tzinfo=None) 就会掉坑里）
- 务必用
datetime.now(timezone.utc)或datetime.utcnow().replace(tzinfo=timezone.utc)（后者更兼容旧代码逻辑） - 避免用
datetime.now()+pytz.timezone('Asia/Shanghai').localize(...)——pytz的localize在 Python 3.9+ 已被标记为 legacy，且与zoneinfo不互通 - 推荐统一用标准库
zoneinfo.ZoneInfo（Python 3.9+）或datetime.timezone构造 UTC 时间；如需本地时区，用ZoneInfo('Asia/Shanghai')
从 MongoDB 读取时间字段后仍是 timezone-aware，但时区可能不是你预期的
MongoDB 本身只存储 UTC 时间戳（毫秒级整数），PyMongo 4 读取时默认还原为 datetime 并附加 timezone.utc。这意味着：无论你写入时用的是 ZoneInfo('Asia/Shanghai') 还是 timezone.utc，读出来永远是 tzinfo=timezone.utc。
- 这是设计使然，不是 bug —— MongoDB 没有时区概念，PyMongo 选择“安全优先”，统一以 UTC 还原
- 如果你需要展示为本地时区（如前端要显示“2024-05-20 14:30:00 上海时间”），必须手动转换：
doc['created_at'].astimezone(ZoneInfo('Asia/Shanghai')) - 注意
astimezone()要求源 datetime 是 aware，所以读取后可直接调用，无需额外判断
使用 datetime.fromisoformat() 解析字符串时容易漏掉时区信息
很多 API 或日志传来的 ISO 格式时间字符串如 "2024-05-20T14:30:00" 是 naive 的，直接 fromisoformat() 会返回无时区对象，写入 PyMongo 4 必然失败。
立即学习“Python免费学习笔记（深入）”；
- 带时区的字符串（如
"2024-05-20T14:30:00+08:00"或"2024-05-20T14:30:00Z"）才能被fromisoformat()正确解析为 aware datetime - 对不带时区的字符串，别用
.replace(tzinfo=...)硬塞 —— 这属于“假装有时区”，可能导致夏令时计算错误（尤其用pytz时） - 更稳妥的做法：明确业务语义。例如所有输入时间都约定为上海本地时间，则用
datetime.fromisoformat(s).replace(tzinfo=ZoneInfo('Asia/Shanghai')).astimezone(timezone.utc)转成 UTC 再存
聚合管道中 $dateFromString 默认输出 naive datetime，不能直接用于写入
在 PyMongo 中执行聚合（如 collection.aggregate([...])）时，若用 $dateFromString 解析字符串字段，其输出结果在 PyMongo 层仍是 naive datetime —— 即使输入字符串含时区，PyMongo 4 也不自动设 tzinfo。
- 这意味着聚合结果里的时间字段，如果直接拿来插入新文档，会触发
tzinfo must be specified - 解决方法：遍历聚合结果，对每个时间字段补上
.replace(tzinfo=timezone.utc)（前提是确认它本就是 UTC）或用.astimezone(timezone.utc)（更安全） - 或者，在聚合阶段就用
$dateFromParts+ 显式指定timezone参数（MongoDB 5.0+ 支持），让服务端直接输出 UTC 时间戳，避免客户端二次处理
datetime 对象一旦被序列化进 BSON（比如作为字典值传给 insert_one），它的 tzinfo 就决定了最终存入 MongoDB 的毫秒值；而这个毫秒值不可逆——你无法从数据库里还原出当初写入时用的是 ZoneInfo('Asia/Shanghai') 还是 timezone.utc。所以时区语义必须靠应用层约定和文档说明来承载。 
