时间与时区处理完全指南:从一次"服务器一迁移,满库时间全偏了"看懂 UTC 存储与 naive/aware 陷阱

2021 年我做一个系统,里面有大量带时间的记录——订单的创建时间、日志的发生时间、用户的预约时间。存时间、用时间这件事,我压根没多想。第一版我做得很省事:记时间不就是 datetime.now() 拿一下当前时间、存进数据库?要展示就读出来格式化成字符串打给用户。本地开发时——真不错:我自己下个单、看一眼记录,时间打出来分毫不差,就是我电脑上那个钟点,几行代码搞定。我心里很踏实:"时间嘛,不就是 now() 存一下、读出来打出来?"可等这个系统真正上线、服务真实用户、还经历了一次服务器迁移,一串问题冒了出来。第一种最先把我打懵:有一次把服务从一台机器迁到另一台,新机器的系统时区设得不一样,迁完之后,数据库里所有历史时间,读出来整体偏了好几个小时——数据一个字没动,可每一条记录的时间都"错"了。第二种最难缠:系统有了不同时区的用户,做日报时我按"今天"去统计,可北京用户的"今天"和纽约用户的"今天",根本不是同一段时间,同一份报表,换个人看数字就对不上。第三种最诡异:有个定时任务在凌晨 1 点半跑,某天它跑了两次,又有一天压根没跑——后来才知道那两天正好是夏令时切换,凌晨 1 点半那个时刻,一天里出现了两次,另一天根本不存在。第四种最莫名其妙:两个时间相减算时长,有时候直接抛异常,有时候算出一个离谱的负数——一个时间带着时区、另一个不带,它们俩压根不能放在一起算。我盯着这一连串问题想了很久才彻底想明白,第一版错在一个根本的认知上:我以为"时间,就是 datetime.now() 拿到的那个数,存下来、读出来就行"。这句话把"一个时刻"和"这个时刻在某个地方显示成的钟点",当成了同一个东西。可它们不是。"一个时刻"和"这个时刻显示成的钟点",是两个不同层面的东西。一个时刻,是宇宙里一个客观的、唯一的点——某件事发生的那一瞬间,全世界只有一个,它和"在哪儿看"无关。而"钟点",比如"下午 3 点",是这个时刻投影到某个时区之后、人能读的一个本地表示——同一个时刻,在北京是下午 3 点,在伦敦就是上午 7 点,它必须绑定一个时区才有意义。datetime.now() 拿到的,恰恰是后者:它是"此刻"在"运行这段代码的机器所在时区"里的钟点,而且它还不把"是哪个时区"这个信息记下来——它给你一个 3 点,却不告诉你这是哪儿的 3 点。把这样一个"不知道是哪儿的钟点"直接存进数据库,你存下的就不是一个确定的时刻,而是一个含义模糊、必须靠"当时那台机器是什么时区"才能解读的数——而那个时区信息,恰恰没被存下来。于是只要机器的时区变了,所有这些数的含义就跟着变了。问题的根子不在某一行取时间的代码,而在你从一开始就没分清"时刻"和"钟点"。真正做对时间处理,核心不是"用 now() 取个时间存下来",而是在系统内部只用带时区的 UTC 时刻、在入口把一切时间归一成 UTC、在出口才按看的人转成本地钟点、把夏令时和"当天"交给时区库去算、绝不用 naive 时间。这篇文章就把时间与时区处理梳理一遍:为什么"now() 存下来就行"是错的、时间该怎么存、naive 与 aware 的区别、边界上怎么转换、夏令时和"今天"怎么处理,以及数据库列类型、序列化、跨时区"当天"、测耗时这些把时间处理真正做扎实要避开的坑。

问题背景

先把那串问题的现象和我的误判讲清楚,后面所有的设计都是冲着纠正这个误判去的。

现象:一套"now() 存下来就行"的时间处理,在系统真正跑起来后冒出一串问题:服务器一迁移、系统时区一变,数据库里所有历史时间整体偏了几小时;有了多时区用户,"今天"算出来因人而异、报表对不上;夏令时切换那天,定时任务多跑一次、又漏跑一次;两个时间相减,一个带时区一个不带,要么抛异常要么算出负数。

我当时的错误认知:"时间,就是 datetime.now() 拿到的那个数,存下来、读出来就行。"

真相:这个认知错在它把"时间"这一个词,糊住了两个不同的东西。一个是"时刻"——某件事发生的那个客观瞬间,全宇宙唯一,和地点无关;另一个是"钟点"——这个时刻在某个时区里显示出来的、人能读的样子,比如"下午 3 点"。这两者之间,差着一个时区:钟点 = 时刻 + 时区。datetime.now() 的问题,是它给你的是一个钟点,却不把"是哪个时区的钟点"这个信息一起给你——它返回的是一个所谓 naive(朴素)的时间,光秃秃一个"3 点",时区那一栏是空的。你把这个空着时区的"3 点"存进数据库,数据库里躺着的就不是一个确定的时刻,而是一个必须靠"存它的时候那台机器是什么时区"才能翻译回时刻的、含义悬空的数。而这个翻译用的钥匙——机器时区——既没被存下来,还会随着迁移、配置而改变。一旦钥匙变了,所有锁着的数,含义全变。开头那四个问题,根上都是这一件事:迁移后整体偏移,是翻译的钥匙换了;多时区"今天"对不上,是不同的人用不同的钥匙翻译;夏令时出错,是时区的偏移量本身会变,而你以为它固定;相减异常,是带钥匙的时刻和不带钥匙的钟点根本不能混算。问题的根子清楚了:这不是"格式化字符串时多写个时区"的小修补,而是要换一个根本的认知——系统里流动的必须始终是"时刻"(带时区的、确定的),"钟点"只是它在最后一刻、为某个人显示出来的样子。

要把时间处理做对,需要几块认知:

• 为什么"now() 存下来就行"是错的——它存的是悬空的钟点,不是确定的时刻;
• 存储——系统内部只用带时区的 UTC 时刻,数据库统一存 UTC;
• naive 与 aware——给时间带上"时区"这个标签,naive 时间一律拒收;
• 边界转换——入口把一切时间转成 UTC,出口才按看的人转回本地;
• 夏令时与"今天"——别用固定偏移硬算,交给 IANA 时区库;
• 数据库列类型、序列化、跨时区当天、测耗时这些工程坑怎么处理。

一、为什么"now() 存下来就行"是错的

先把这件最根本的事钉死:"now() 存下来就行"错在它默认了一件根本不成立的事——它默认"时间"是绝对的、和地点无关的,所以拿到一个时间值,直接存、直接读,就万事大吉。可时间从来不是绝对的。你说"3 点",这句话本身是不完整的:是哪儿的 3 点?同一个客观瞬间,北京的钟显示 3 点,伦敦的钟显示 7 点——它们指的是同一个时刻,只是钟点不同。这意味着,一个时间值只有同时带着"时区"这个信息,才能唯一地、无歧义地指向一个真实的时刻;一旦把时区信息抹掉,剩下的那个光秃秃的数字,就只是一个"某个不知名的钟上的读数",它对应的真实时刻有无数种可能。datetime.now() 干的恰恰就是抹掉时区这件事:它返回的是运行机器所在时区的当前钟点,但返回值里不带任何时区标记。你以为你存下了"事情发生的时刻",其实你只存下了"当时那台机器的钟面上写着几点"。这两者之间隔着的,正是那个被你丢掉的、又会随机器配置而变的时区。第一版所有的麻烦,都是从"丢掉时区"这一下开始的。

下面这段代码,就是我那个"本地怎么看都对、一迁移就全偏"的第一版:

# 反面教材:用 naive 的本地时间存储、运算
from datetime import datetime

def create_order(user_id):
    order = {
        "user_id": user_id,
        "created_at": datetime.now(),       # 破绽 1:naive 时间,不带时区,含义悬空
    }
    db.insert(order)
    return order

def order_age_seconds(order):
    """算这笔订单到现在过了多少秒。"""
    now = datetime.now()                    # 破绽 2:依赖机器当前时区,迁移即错
    return (now - order["created_at"]).total_seconds()  # 破绽 3:一旦混入 aware 时间直接抛异常

这段代码在本地开发时表现不错,因为本地存时间、读时间、算时间,全发生在同一台机器、同一个时区里——存进去时丢掉的那把"时区钥匙",读出来时恰好又是同一把,一丢一捡,刚好抵消,你看不出任何破绽。它的问题不在某一行语法上——datetime.now()、两个时间相减,语法都对——而在它全程使用 naive 时间:created_at 从存进去的那一刻起,就不是一个确定的时刻,而是一个悬空的钟点;它的含义全靠"读它的机器恰好和写它的机器同时区"这个巧合在维系——而服务器迁移、容器换镜像、跨时区用户,每一个都会打破这个巧合。这三个破绽对应的,正是开头那几类事故。问题的根子清楚了:做对时间处理,第一步不是优化格式化,而是承认"时间值必须带时区才有意义",然后让系统里从头到尾流动的,都是带时区的、确定的时刻。下面五节,就是这件事怎么落地。

二、存储:系统内部只用 UTC 时刻

既然时间值必须带时区,那第一个要定的规矩就是:系统内部,统一用哪个时区?答案是 UTC。UTC 是一个不随地点、不随季节、永不变化的基准时区——它没有夏令时,全世界对它的定义完全一致。所以系统里的"现在",永远该这样取:

from datetime import datetime, timezone

def now_utc():
    """永远拿"带时区信息(UTC)的当前时刻" —— 这是系统里唯一该用的"现在"。"""
    return datetime.now(timezone.utc)

# datetime.now()             -> naive,不知道是哪个时区的钟点,禁用
# datetime.utcnow()          -> 也是 naive!值虽是 UTC,却不带 tzinfo 标记,同样禁用
# datetime.now(timezone.utc) -> aware,值是 UTC、且明确标着 UTC,这才对

这里的认知要点是:系统内部统一用 UTC,核心不是"UTC 这个时区有什么特别神奇",而是"统一"这件事本身。你完全可以想象一个系统内部统一用北京时间,只要处处都是北京时间、绝不混入别的,逻辑上也能自洽。但 UTC 比任何一个具体地区的时区都更适合当这个"内部基准",原因有两个:第一,它没有夏令时——一个地区的时区,一年里偏移量会跳变两次(夏令时开始、结束),拿它当基准,你的"基准"自己都在动;UTC 的偏移量恒定,它是一把永不变形的尺子。第二,它中立——不偏向任何地区的用户,也不会因为你公司搬了办公室、服务器换了机房而需要改。所以规矩是:时刻一旦进入系统,立刻换算成 UTC;之后内部所有的存储、比较、运算,全在 UTC 下进行;只有到了最后要展示给某个具体的人看时,才转成那个人的本地时区。这里还有一个极其常见、极其隐蔽的坑必须点名:datetime.utcnow()。很多人以为它就是"正确的 UTC 时间",于是放心地用。但它返回的是一个 naive 时间——它的值确实是 UTC 的钟点,可它不带 tzinfo 标记,它没把"我是 UTC"这件事写在脸上。你把它和一个 aware 时间放一起运算,Python 会直接报错;你把它当本地时间用,又会错。datetime.utcnow() 是"对的值 + 错的类型",而 datetime.now(timezone.utc) 才是"对的值 + 对的类型"。记住:取当前 UTC 时间,只用后者。系统内部统一了 UTC,可怎么从机制上保证不让 naive 时间溜进来?这要靠下一节。

三、naive 与 aware:naive 时间一律拒收

前面反复提到 naive 和 aware,这是时间处理里最该分清的一对概念。aware(有意识的)时间,带着 tzinfo——它知道自己是哪个时区的,是一个确定的时刻;naive(朴素的)时间,tzinfo 是空的——它只是个悬空的钟点。系统里所有的麻烦,几乎都源于 naive 时间溜了进来。所以要做两件事,第一,能判断一个时间到底是哪种:

def is_aware(dt):
    """判断一个 datetime 带不带时区:tzinfo 为空,就是 naive(危险)。"""
    return dt.tzinfo is not None and dt.tzinfo.utcoffset(dt) is not None

第二,在系统的入口设一道关——naive 时间一律拒收,从源头上杜绝悬空的钟点流进来:

def require_aware(dt):
    """系统边界上设一道关:naive 时间一律拒收,从源头杜绝含义悬空的时间。"""
    if not is_aware(dt):
        raise ValueError("拒绝 naive 时间:时间必须带时区信息才能进入系统")
    return dt

这里的认知要点是:naive 和 aware 这对概念,值得你把它刻进肌肉记忆,因为它就是"钟点"和"时刻"那个根本区别,在代码层面的具体体现。一个 aware datetime,带着 tzinfo,它是一个完整的、确定的时刻——你拿着它,可以毫无歧义地把它转换到任何时区。一个 naive datetime,tzinfo 是空的,它只是一串"年月日时分秒"的数字,你不知道这串数字是站在哪个时区读出来的,所以你根本无法可靠地把它转换到别的时区——你缺一把钥匙。require_aware 这道关的意义,就在于它把"系统里到底允不允许出现 naive 时间"这个问题,从一个"靠每个开发者自觉"的约定,变成了一条"代码强制执行"的边界规则。为什么要这么强硬?因为 naive 时间最坏的地方,不是它会立刻报错——恰恰相反,它常常不报错,它会安安静静地、带着错误的含义一路跑下去,直到很久以后在某个对账、某次迁移里,以一个谁也想不到的方式爆出来。一个会立刻抛异常的错误是友好的,一个安静地把错误数据存下来的错误才真正致命。require_aware 做的,就是把"naive 时间"这个安静的、慢性的错误,转化成一个"在入口处立刻、响亮地抛异常"的错误——让它在离源头最近、最好查的地方就暴露,而不是流到深处去酿成事故。一句话:不要试图去"容忍"naive 时间,要做的是在边界上把它彻底挡在门外。知道了要挡 naive、要用 aware,接下来就是入口和出口具体怎么转——这是下一节。

四、边界转换:入口转 UTC,出口转本地

有了"内部只跑 UTC、naive 一律拒收"这两条,系统就有了一个清晰的形状:一个内部全是 UTC 的核心,外面包着一层负责转换的边界。入口处,把进来的任何时间归一成 UTC:

def to_utc(dt):
    """入口转换:任何进入系统的时间,先归一成 UTC,之后内部只跑 UTC。"""
    require_aware(dt)                    # 不带时区的时间无法可靠转换,先在门口挡掉
    return dt.astimezone(timezone.utc)

如果进来的时间来自客户端、可能压根没带时区,那就按事先约定的时区把它补全,绝不默默当成服务器时区:

from zoneinfo import ZoneInfo

def parse_client_time(raw, default_tz):
    """解析客户端时间:带偏移就直接用,没带就按约定时区补全,绝不留 naive。"""
    dt = datetime.fromisoformat(raw)
    if not is_aware(dt):
        # 客户端没给时区:按事先和前端约定好的时区补,而不是默默套用服务器时区
        dt = dt.replace(tzinfo=ZoneInfo(default_tz))
    return dt.astimezone(timezone.utc)

出口处,反过来——把内部的 UTC 时刻,按"看的人在哪个时区"转成本地钟点:

def to_local(dt_utc, tz_name):
    """出口转换:展示给用户前,才把 UTC 转成该用户所在时区的本地钟点。"""
    require_aware(dt_utc)
    return dt_utc.astimezone(ZoneInfo(tz_name))

# 存的是同一个 UTC 时刻,展示时按"看的人是谁"转 —— 北京用户和纽约用户看到不同钟点

下面这张图,把时间在系统里的流动画出来:

这里的认知要点是:边界转换这套设计,本质上是给系统画了一道"内外有别"的圈。圈内,是一个纯净的世界——里面流动的每一个时间,都是 UTC,都是确定的时刻,所以圈内的代码可以放心大胆地存储、比较、相减,永远不会遇到时区的麻烦,因为根本没有第二个时区存在。圈外,是混乱的真实世界——用户来自五湖四海,客户端有的带时区有的不带,上游系统各用各的约定。边界转换层,就是这道圈的圈壁:它的唯一职责,就是在时间"入圈"时把它洗成 UTC、在时间"出圈"时把它染成某个人的本地钟点。这个设计的好处是,它把"处理时区"这件麻烦事,从"散落在系统每一个角落"收拢到了"只在边界这一层"。你的业务核心代码——算订单时长、判断是否过期、排序——完全不需要知道时区的存在。这里有两个细节要拎清。第一,入口处遇到不带时区的客户端时间,正确做法是 replace(tzinfo=约定时区),而绝不是想当然地按服务器时区解读——"约定时区"是你和前端事先讲好的(比如统一用 UTC,或统一用某个业务所在地时区),它是明确的;而"服务器时区"是个会变的、不该被业务依赖的环境配置。第二,出口的 to_local 需要一个 tz_name 参数——这逼着你回答"这个时间是给谁看的",而这正是对的:展示用的钟点,本就该取决于看的人是谁。入口出口转换的主干清楚了,可时区里还藏着一个最不讲道理的东西——夏令时。

五、夏令时与"今天":交给时区库,别自己硬算

前面说 UTC 偏移量恒定,可具体地区的时区不是——很多地区有夏令时:一年里某天把钟拨快一小时,又某天拨回来。这意味着一个地区的时区偏移量一年里会变两次。处理这个,绝不能用固定偏移量硬算,必须交给 IANA 时区数据库(Python 里就是 zoneinfo):

from datetime import datetime, timezone, timedelta
from zoneinfo import ZoneInfo

# 对的:用 IANA 时区名,zoneinfo 自带夏令时规则,该拨快拨慢它自己算
ny = ZoneInfo("America/New_York")
summer = datetime(2024, 7, 1, 12, 0, tzinfo=ny)    # 夏季:偏移自动是 UTC-4
winter = datetime(2024, 1, 1, 12, 0, tzinfo=ny)    # 冬季:偏移自动是 UTC-5

# 错的:用固定偏移量硬编码 "美东就是 UTC-5" —— 夏令时一到就错一小时
wrong = datetime(2024, 7, 1, 12, 0, tzinfo=timezone(timedelta(hours=-5)))

夏令时还会污染一个看似简单的需求——"某个用户的今天"。一个用户的"今天",是他所在时区的 0 点到次日 0 点,要先在他的时区里定边界,再转成 UTC 去查:

def user_day_range(date_str, tz_name):
    """一个用户的"今天":是他所在时区的 0 点到次日 0 点,换算成 UTC 区间。"""
    tz = ZoneInfo(tz_name)
    start_local = datetime.fromisoformat(date_str).replace(tzinfo=tz)
    end_local = start_local + timedelta(days=1)
    # 查库时,用这一对 UTC 边界去框,而不是拿 UTC 的"今天"硬套到所有人头上
    return start_local.astimezone(timezone.utc), end_local.astimezone(timezone.utc)

这里的认知要点是:夏令时这件事教给你的最深的一课是:时区不是一个固定的数字,而是一套随时间变化的规则。"美国东部时间"不等于"UTC 减 5 小时"——它夏天是减 4、冬天是减 5,而且"哪天开始算夏天"这个规则,各个国家还不一样、历史上还改过好几次。你绝不可能、也不应该把这套庞杂又善变的规则,自己写进代码里。这正是 IANA 时区数据库存在的意义:它由专人维护着全世界每一个时区、每一次夏令时调整、每一次规则变更的完整历史。你要做的,就是认准时区的 IANA 名字——是 "America/New_York" 这样的"地区/城市"格式,而不是 "EST"、"UTC-5" 这种偏移量——把这个名字交给 zoneinfo,剩下的"这一天这个时区偏移多少",它会替你查得分毫不差。再说"今天"这个坑。"今天"听起来是个绝对的概念,其实它和时区死死绑在一起:当北京已经是 11 月 4 号的上午,纽约还停在 11 月 3 号的晚上。所以"统计今天的订单"这个需求,根本没有一个全局唯一的答案——它必须先问"谁的今天"。user_day_range 做的就是这件事:它先在用户自己的时区里,把"今天"这一天的 0 点和 24 点两个边界定下来,再把这两个边界转成 UTC,拿去数据库里框数据。错误的做法,是图省事拿 UTC 的 0 点当所有人的"一天起点"——那样的话,凡是不在 UTC 时区的用户,他的"一天"边界就是错位的,跨过午夜的那几笔订单,就会被算进错误的日子里。"今天"不是绝对的,它永远是"某个时区的今天"。主干都齐了,最后是几个把时间处理真正用到生产里才会撞见的工程坑。

六、工程坑:数据库列类型、序列化、测耗时

主干之外,还有几个工程坑,不处理就会让你的时间处理在边角上漏时区。坑 1:序列化用 ISO 8601、带上偏移量。时间要落库、要进 JSON,转成字符串时必须把时区信息一起带上,用 ISO 8601 格式——这样任何系统读到它,都不会有歧义:

def to_iso(dt):
    """落库 / 传输统一用 ISO 8601 带偏移量的字符串,时区信息一并带上。"""
    require_aware(dt)
    return dt.astimezone(timezone.utc).isoformat()
    # 形如 "2024-11-03T05:30:00+00:00" —— 自带 UTC 标记,任何系统读它都不歧义

def from_iso(s):
    """读取:fromisoformat 能还原出 aware datetime,偏移量信息一点不丢。"""
    dt = datetime.fromisoformat(s)
    return require_aware(dt)

坑 2:测"过了多久"要用单调时钟,不能用 datetime。测一段代码跑了多久,如果用两次 datetime.now() 相减,一旦中途系统时间被 NTP 对时回拨、或夏令时切换,你会算出一个负数或跳变的耗时。测时长要用单调时钟——它只会前进:

import time

def measure(task):
    """测"过了多久"用单调时钟,绝不用 datetime —— 它不受改表、对时影响。"""
    start = time.monotonic()             # 单调时钟:只会前进,系统时间被回拨也不受影响
    task()
    return time.monotonic() - start      # 算出的耗时永远是正的、可信的

坑 3:数据库时间列,选对类型、想清楚它存不存时区。不同数据库对时间列的处理差别很大:有的类型存的是带时区的时刻(如 PostgreSQL 的 timestamptz),有的存的是不带时区的钟点(如 timestamp、MySQL 的 DATETIME)。规矩是:要么用带时区的列类型,要么用不带时区的列、但全系统铁律只往里存 UTC——绝不能"存的时候是本地、读的时候靠连接时区蒙"。坑 4:别信"服务器时区"。代码里任何依赖"机器当前是什么时区"的逻辑,都是定时炸弹——换机房、换容器镜像、改个系统配置,时区就变了。正确的做法是把服务进程的时区显式锁成 UTC(比如设 TZ=UTC),让"服务器时区"这个变量压根不参与任何业务计算。坑 5:闰秒不归你管,但要知道它存在。偶尔会有"闰秒"——某一分钟有 61 秒。绝大多数业务系统不需要自己处理它(交给操作系统的对时),但你要知道"两个时间戳相减得到的秒数,不一定等于真实流逝的物理秒数",关键的计时仍以单调时钟为准。坑 6:存"未来的预约时间",存法要再想一层。对已经发生的事件,存 UTC 没有任何问题。但对未来的预约——比如用户约了"三个月后上午 9 点开会"——如果那地区在这三个月里改了夏令时规则,你当初换算好的那个 UTC 时刻,届时对应的本地钟点就不再是 9 点了。这种场景,更稳妥的是把用户原始输入的"本地钟点 + 时区名"也一并存下来,而不只存换算后的 UTC。坑 7:日志时间戳统一 UTC。多台服务器、多个时区,日志若各记各的本地时间,出事时没法把不同机器的日志按时间对齐。所有日志的时间戳,统一用 UTC、统一带偏移量。

关键概念速查

避坑清单

1. 分清"时刻"和"钟点",时间值必须带时区才能唯一确定一个时刻。
2. 别用 datetime.now() 存时间,它给的是悬空的本地钟点、丢了时区。
3. 系统内部统一用 UTC,取当前时间只用 datetime.now(timezone.utc)。
4. 别用 datetime.utcnow(),它值对类型错,是个 naive 时间。
5. 在系统入口设关卡,naive 时间一律拒收,从源头杜绝悬空时间。
6. 入口把一切时间转成 UTC,出口才按看的人所在时区转回本地钟点。
7. 夏令时交给 IANA 时区库,用"地区/城市"时区名,别用固定偏移硬算。
8. "今天"先问"谁的今天",按用户时区定边界再换算成 UTC 查询。
9. 测耗时用单调时钟 monotonic,绝不用两次 datetime 相减。
10. 数据库时间列选对类型、统一存 UTC,序列化用 ISO 8601 带偏移量。

总结

回头看那串"迁移后时间整体偏移、多时区今天对不上、夏令时定时任务乱跑、相减抛异常"的问题,以及我后来在时间处理上接连踩的坑,最该记住的不是某一个转换函数的写法,而是我动手前那个想当然的判断——"时间,就是 datetime.now() 拿到的那个数,存下来、读出来就行"。这句话错在它把"一个时刻"和"这个时刻显示成的钟点",当成了同一个东西。我以为取到时间、存进去、读出来,这件事就办成了。可我忽略了一件最要紧的事:now() 给我的,不是"事情发生的那个客观时刻",而是"运行这段代码的机器,钟面上当时写着几点"。这两者之间,差着一个时区——而 now() 恰恰把这个时区信息给抹掉了。我存进数据库的,于是不是一个确定的时刻,而是一个含义悬空、必须靠"当时那台机器是什么时区"才能翻译的数;偏偏那把翻译的钥匙既没被存下来,还会随着迁移、配置而改变。这个错配,本地开发时根本看不出来——因为本地存、读、算全在同一台机器同一个时区里,丢掉的时区又被原样捡了回来;它只会在服务器迁移、多时区用户、夏令时切换这些"翻译钥匙变了"的时刻,以一种谁也想不到的方式爆出来。

所以做对时间处理,真正的功夫不在"写一个格式化函数"那几行上。格式化本身不难。真正的功夫,在于你要从一开始就承认"时间值必须带时区才有意义",然后让系统里从头到尾流动的,都是带时区的、确定的 UTC 时刻:你不能用 naive 时间,就内部统一 UTC、取"现在"只用 now(timezone.utc);你怕悬空时间溜进来,就在入口设一道关、naive 一律拒收;真实世界的时间五花八门,就在边界上入口转 UTC、出口转本地;夏令时不讲道理,就把它整个交给 IANA 时区库、绝不自己用偏移量硬算;而到了数据库列类型、序列化、测耗时这些边角上,你还要处处守住,别让时区又偷偷漏掉。这篇文章的几节,其实就是顺着这套规矩展开的:先想清楚"now() 存下来就行"为什么错,再讲 UTC 怎么存、naive 与 aware 怎么分、边界怎么转换、夏令时和"今天"怎么处理,最后是数据库、序列化、测耗时这几个把时间守扎实的工程细节。

你会发现,时间处理这件事,和现实里"一家跨国公司怎么开一场全球电话会议"完全相通。一个不靠谱的助理会怎么定会议时间?他坐在上海的办公室,在邮件里写一句"会议定在 3 点",就群发了出去。他心里想的是上海的下午 3 点,可邮件里压根没写是哪儿的 3 点——伦敦的同事按伦敦时间 3 点掐着点上线,纽约的同事按纽约时间 3 点上线,没有一个人和他对得上;更糟的是,过两周纽约那边夏令时一调,连"差几个小时"这个账都跟着变了,可谁也没把这茬算进去。而一个靠谱的助理怎么做?他绝不在邮件里写一个光秃秃的"3 点"。他先把会议时间锚定到一个全球唯一、谁都不会误解的基准上——"UTC 时间 7 点整"(这就是内部统一 UTC);发给每个同事时,他再贴心地按各人所在的城市,换算成当地的钟点——"上海同事:你们的下午 3 点;伦敦同事:你们的上午 7 点"(这就是出口按人转本地);碰上夏令时,他不去自己心算"差几小时",而是直接查每个城市的标准时区,让工具替他算准(这就是交给时区库)。同样是定一个会议时间,不靠谱的助理发出一个含义悬空的钟点、让全世界各自猜,靠谱的助理锚定一个确定的时刻、再替每个人翻译成他看得懂的钟点——差别不在"定时间这件事本身难不难",只在助理心里有没有"3 点必须说清是哪儿的 3 点"这根弦。

最后想说,时间处理做没做对,差距永远不会在"本地开发、自己存一个读一个"时暴露——本地你存时间、读时间、算时间全在同一台机器、同一个时区里,now() 丢掉的那把时区钥匙,读的时候恰好又是同一把、一丢一捡刚好抵消,你那行 datetime.now() 打出来分毫不差,你自然觉得"时间嘛,now() 存一下"一点问题都没有。它只在真实的、跨多个时区的用户、会迁移会换机房、还要跨过夏令时的生产环境里才显形。那时候它会用最难堪的方式给你结账:做不好,你会因为一次服务器迁移,眼睁睁看着数据库里所有历史时间整体偏移,会因为没分清"谁的今天",让同一份报表换个人看就对不上,会因为用偏移量硬算,让定时任务在夏令时那天多跑一次又漏跑一次;而做对了,你的每一个时间从进入系统起就是带时区的、确定的 UTC 时刻,迁移多少次都纹丝不动,展示给谁就是谁的本地钟点,夏令时怎么折腾都由时区库替你算准。所以别等"一次迁移让满库时间全偏"那一刻找上门,在你写下每一个取时间、存时间的变量时就该想清楚:这个时间带时区了吗、是不是 naive、存的是不是 UTC、展示时按谁的时区转、夏令时我交给时区库了吗,这一道道关口,我是不是都替这个时间守住了?这些问题有了答案,你交付的才不只是一套"本地看着对"的代码,而是一个无论跨多少时区、迁移多少回、跨过多少次夏令时,每一个时刻都精确无误的、让人放心的系统。

—— 别看了 · 2026