1. 先把"日期时间"这件事拆开：模块划分与核心认知
讲真，Python 里日期时间看起来是最不需要上心的模块之一，import datetime就是一行的事。但这些年我见过太多项目栽在它手上，不是不会用，而是没搞明白这套东西在 Python 里到底分了几层。今天这篇就按我自己的理解，把 Python 的日期时间体系从头捋一遍。
1.1 从 time 模块说起：时间戳、struct_time 和本地时区
很多人以为处理日期时间直接上datetime就行，其实time模块才是 Python 最早的那套方案。它不是被淘汰了，而是职责不同。
time.time()返回的是一个 Unix 时间戳，也就是从 1970 年 1 月 1 日 00:00:00 UTC 起到现在的秒数，用浮点数表示。这套东西的好处是计算极快、存储非常简单，坏处是它跟"人看得懂的年月日"完全不沾边。你看着1735672785.12这种数，除非专门转换，否则根本不知道它是某年某月某日的几点。
time.localtime()和time.gmtime()则返回一个叫struct_time的具名元组，里面是tm_year、tm_mon、tm_mday这类字段。localtime会把时间戳转换成本地时区下的墙钟时间，gmtime转成 UTC。这里有一个新手最容易踩到的点：struct_time里没有时区信息，它只是"某个时区视角下的一组数字"。
我做项目时的习惯是，time模块只用来做两件事：第一，拿time.time()做高精度计时；第二，跟 C 语言遗留的接口对接。其余日常日期逻辑，全部交给datetime。
1.2 datetime 模块的四件套：date、time、datetime、timedelta
datetime模块里有四个核心类，名字看着像，实际分工完全不同：
date：只关心年、月、日，比如"今天是 2025 年 1 月 1 日"。time：只关心时、分、秒、微秒，比如"下午 14:30:45"。datetime：两者合体，年月日时分秒全都有，是日常用得最多的类。timedelta：表示两个日期时间之间的差值，可以理解为"一段时间"，比如"差 3 天 5 小时"。
这几个类藏在同一个模块里，所以经常有人写from datetime import datetime然后发现自己还想用date，得再导一次。这是 Python 里少见的"同名模块内部又有同名类"的情况，很容易让新手绕晕。
我个人的建议是：所有需要落库、展示、计算的业务时间统一用datetime；date只用来处理生日、节假日这类不需要具体时刻的场景；time类用得最少，通常只在处理"每天固定时间点"这类需求时才碰。
1.3 naive 与 aware：最容易忽略的"有没有时区"问题
这是整个 Python 日期时间体系里最核心、也最容易被忽略的一点。
一个datetime对象如果没带tzinfo，它就是一个 naive 对象，字面意思是"天真"——因为它不知道自己是哪个时区的。比如datetime(2025, 1, 1, 12, 0)，你说这是中午 12 点，可它到底是北京中午、东京中午还是纽约中午？没有时区信息，谁也不知道。
带上了tzinfo的对象叫 aware 对象，它明确知道自己属于哪个时区，也就知道这个时间对应的 UTC 时刻是多少。
正是因为 naive 和 aware 的混用，项目里才会出现各种莫名其妙的 Bug：明明存了一个"北京时间"，拿去跟 UTC 时间一比较，发现差 8 小时；或者同一个日期变量，在不同的机器上打印出来不一样。这些问题后面有一整章要展开，这里先记住一个原则：存储和计算尽量用 aware 时间，展示和输入再用本地时间。
2. 日常最常用的构造与运算套路：从创建到比较
把基础概念捋清楚之后，我们看看实际开发里最常用到的创建、运算和比较操作。这些代码看起来简单，但组合起来能解决绝大多数业务需求。
2.1 创建时间的五种姿势
我总结了五种常见的创建datetime的方式，按使用频率排：
- 直接构造：
datetime(2025, 1, 1, 12, 30, 45)。适合已知具体年月日的场景，比如配置里的固定时间点。 - 取当前时间：
datetime.now()拿本地时间，datetime.now(timezone.utc)拿当前 UTC 时间。前者返回 naive，后者返回 aware，这是老生常谈的坑。 - 从字符串解析：
datetime.strptime("2025-01-01 12:30:45", "%Y-%m-%d %H:%M:%S")，后面专门讲。 - 从时间戳转换：
datetime.fromtimestamp(1735672785)转本地时间，datetime.fromtimestamp(1735672785, tz=timezone.utc)转成指定时区。 - 组合：
datetime.combine(date(2025, 1, 1), time(12, 30))，把 date 和 time 拼起来。
这几种姿势里，我踩过的最深的一个坑是datetime.now()的时区歧义。比如某台服务器系统时区设成了 UTC，你用datetime.now()得到的是 UTC 时间，但业务方以为这是本地时间，存进数据库后再用别的机器读出来，直接就串了。所以我现在的习惯是，凡是now()，几乎一律写datetime.now(timezone.utc)，从源头杜绝歧义。
2.2 日期加减与 timedelta 的边界
datetime加减timedelta是最基本的运算能力。timedelta(days=1)就是加一天，timedelta(hours=-2)就是减两小时，正负值都支持。datetime1 - datetime2的结果也是一个timedelta，这个减法特别适合做倒计时、算年龄、算时长。
但这里有个很关键的边界：timedelta只能加天数、秒数、微秒数，不能直接加"一个月"或"一年"。因为一个月的长度不固定，有的 28 天，有的 29 天，有的 31 天。你没法用固定秒数表示"下个月同一时间"。
所以当你需要做"三个月后""去年此时"这种日历级别的推算时，timedelta就不够用了，得用dateutil.relativedelta：
from dateutil.relativedelta import relativedelta from datetime import datetime now = datetime.now() three_months_later = now + relativedelta(months=3)relativedelta能正确处理月末、闰年这类日历规则。比如 1 月 31 日加一个月，它会给你 2 月 28 日或 29 日，而不是把一个不存在的 2 月 31 日抛给你。
2.3 比较、排序与跨时区换算
datetime之间可以直接用<、>、==比较，也可以用sorted()排序。比较时系统会比较它们对应的绝对时间，前提是两个对象要么都是 naive，要么都是 aware。
naive 和 aware 混在一起比较是另外一个重灾区。我印象很深的一次：一段程序从数据库读出一批时间，其中一部分是空值时程序补了一个 naivedatetime.min，另一部分是从 API 拿到的带时区时间，结果一排序直接抛TypeError。排查了半天，最后发现是datetime.min这个默认值没带时区。
跨时区换算的正确做法是先把对象的tzinfo补上，再用astimezone()转换：
from datetime import datetime, timezone from zoneinfo import ZoneInfo # 北京时间转纽约时间 bj = datetime(2025, 1, 1, 12, 0, tzinfo=ZoneInfo("Asia/Shanghai")) ny = bj.astimezone(ZoneInfo("America/New_York")) print(ny) # 输出带纽约时区偏移的时间记住一个心法：比较之前先统一到 UTC，展示之前再转回目标时区。这样想，整条链路就通了。
3. 字符串解析与格式化的细节，以及常见翻车点
日期时间跟字符串的转换是绕不开的一环。前端传来的表单、日志里输出的记录、数据库里的字段，到处都是字符串形态的时间。这里面的格式代码和版本差异，值得单独拿出一章来讲。
3.1 strftime/strptime 的格式代码陷阱
datetime.strftime()把时间对象格式化成字符串，datetime.strptime()把字符串解析成时间对象。两者共用一套格式代码，常见的有这些：
| 代码 | 含义 | 示例 |
|---|---|---|
%Y | 四位年份 | 2025 |
%y | 两位年份 | 25 |
%m | 两位月份 | 01 |
%d | 两位日期 | 09 |
%H | 24 小时制的小时 | 14 |
%I | 12 小时制的小时 | 02 |
%M | 分钟 | 45 |
%S | 秒 | 09 |
%f | 微秒 | 123456 |
%p | AM/PM | PM |
最经典的翻车点就是%m和%M。%m是 month，%M是 minute，我就见过不止一次把分钟写成%m，结果解析出来的时间秒钟对、小时对，就是月份变成了当天的分钟数，相当离谱。
还有%I和%H也容易混。如果用了%I这种 12 小时制，必须配合%p，否则你永远不知道 02 是下午还是凌晨。
另外一个易忽略的点是区域设置。%b（月份的英文缩写）和%p这类输出内容依赖系统的 locale 设置，不同环境下格式化出来的结果可能不一样。我自己就遇到过一台服务器输出Jan，另一台输出1月的情况。所以给第三方 API 或者日志系统做格式化时，最好不要依赖英文缩写。
3.2 ISO 8601 与 fromisoformat 的版本差异
现在绝大多数 JSON 接口里传的时间都是 ISO 8601 格式，比如2025-01-01T12:30:45+08:00。Python 里解析这个格式优先用datetime.fromisoformat()。
注意这个函数在不同 Python 版本里的能力差异很大。Python 3.7 到 3.10 的fromisoformat()只能解析有限几种格式，对带Z后缀的 UTC 时间支持不好。如果你写的是datetime.fromisoformat("2025-01-01T12:30:45Z")，在旧版本里大概率直接报错，因为Z不是合法的时区偏移。
Python 3.11 之后，fromisoformat()的解析能力大幅增强，ISO 8601 标准里的常见写法基本都能吃下，Z也能正常解析成 UTC。所以如果你还在维护老项目，又不想受版本限制，可以考虑下面两种方案：
- 自己先做字符串替换，把末尾的
Z换成+00:00，再用fromisoformat()。 - 用第三方库
python-dateutil里的dateutil.parser.isoparse()，它解析 ISO 格式更宽容。
3.3 解析失败与模糊输入的处理策略
datetime.strptime()的解析非常严格，格式稍微对不上就抛ValueError。比如你给了%Y-%m-%d，结果传进来一个2025/01/01，直接崩溃。有人为此专门写了各种复杂正则，其实大可不必。
我给团队定的规矩是这样的：
- 如果时间字符串来自内部系统，格式是固定的，就用
strptime，同时把解析包在try/except里，记录一个带上下文日志的告警。 - 如果时间字符串来自用户输入、第三方接口，格式不可控，就用
dateutil.parser.parse()，它能识别一大堆常见写法，甚至是"昨天""明天"这种自然语言描述。当然，宽容的代价是它也可能把一些奇怪的输入解析成你没想到的结果，所以用之前最好先做格式白名单判断。
服务端接收前端传的时间，最稳的做法是要求前端直接传 ISO 8601 字符串，而不是传"2025.1.1"或者"2025年1月1日"这种五花八门的格式。接口契约里定死格式，能省掉无数解析 bug。
4. 时区、夏令时和 zoneinfo：真正决定生产质量的部分
如果上面的内容还只是在"会用"的阶段，那么时区处理直接决定了你写的日期时间代码是不是"专业级"的。这里没有任何捷径，只有把 UTC、IANA 时区数据库和夏令时这三个事彻底理解透。
4.1 为什么明明有时区还是要小心"墙钟时间"
很多人有个误解：看到一个 ISO 字符串末尾有+08:00，就觉得它已经包含时区信息了，安全了。实际上，时区偏移只能告诉你"这一刻跟 UTC 差多少"，不能告诉你"这个地区一般用哪个时区规则"。
举个例子，2025-01-01T12:00:00+08:00和2025-06-01T12:00:00+08:00，都是 +08:00 偏移，看起来没区别。但有些地区还实行夏令时，夏天的偏移跟冬天完全不同。你拿着一个固定偏移去做未来时间推算，极有可能算错。
正确的做法是用 IANA 时区名，比如Asia/Shanghai、America/New_York、Europe/Berlin这样的字符串，因为它不仅包含了当前偏移，还包含了历史上和未来的夏令时切换规则。
Python 3.9 开始内置了zoneinfo模块，专门用来读取 IANA 时区数据库。ZoneInfo("Asia/Shanghai")就可以直接作为tzinfo参数使用，不必再依赖第三方库。
4.2 zoneinfo 的正确打开方式，以及 DST 的"不存在时间"与"重复时间"
使用zoneinfo时有个常见误区：ZoneInfo("America/New_York")拿到的不是一个固定偏移对象，而是一个会随时间变化的时区规则对象。它内部存的是整个规则表，所以同一个 ZoneInfo 对象用在冬天和夏天，计算出的偏移可能不同。
夏令时切换导致的经典问题有两个：
第一个是不存在的时间。比如美国 2024 年 3 月 10 日切换到夏令时，凌晨 2 点直接跳到 3 点，所以当地 2:30 这个时刻根本不存在。如果你拿这个时间去构造一个带纽约时区的 datetime，结果会很尴尬——它不会老老实实报错，而是会被解释成 3:30，让你完全摸不着头脑。
第二个是重复的时间。秋季结束夏令时时，比如美国 2024 年 11 月 3 日，时钟会从凌晨 2 点调回 1 点，所以 1:30 会经历两次。这时候同一个墙钟时间其实对应两个不同的 UTC 时刻，具体取哪个取决于你声明的是第一次还是第二次。Python 里用fold属性来区分：
from datetime import datetime from zoneinfo import ZoneInfo ny = ZoneInfo("America/New_York") # fold=0 表示第一次经过 1:30 first = datetime(2024, 11, 3, 1, 30, tzinfo=ny, fold=0) # fold=1 表示第二次经过 1:30 second = datetime(2024, 11, 3, 1, 30, tzinfo=ny, fold=1) print(first == second) # False，因为对应不同的 UTC 时刻如果你不做夏令时相关的业务，这个细节可能永远碰不到；但只要你在做排班、会议、定时任务这类和时间强相关的功能，就一定要有"夏令时切换会改变偏移"这根弦。
4.3 在项目中落地：存储、传输与展示的时区策略
我在不同团队里看到过各种时区处理的混搭方案，最后能长期稳定运行的都遵循同一条规则：
- 数据库存储统一用 UTC。要么存 UTC 的
datetime，要么存 Unix 时间戳。这样任何语言、任何时区的服务端都可以正确解读。 - API 传输统一用 ISO 8601 字符串，且带时区偏移。比如
2025-01-01T12:30:45+00:00，这样消费方不需要额外配置时区。 - 前端展示时再转换到用户本地时区。这一步通常在前端做，后端只需要保证给出去的是准确的 UTC 时刻。
这样做的好处是，后端代码里永远只有一套基准时间，不需要为每个国家的用户单独维护一套本地时间逻辑。我自己做国际化的项目时，连日志里都统一用 UTC 加毫秒，排起问题来非常痛快。
5. 实际业务里躲不开的边界与坑：5 个自查点
章节最后，我把自己这些年踩过的坑整理成五个自查点，每一条都对应着真实项目里出现过的线上事故。建议大家写完日期时间相关代码后，挨个过一遍。
5.1 用 naive 还是 aware：统一标准是第一步
我在不同代码仓库里见到过太多混用案例：有的接口返回 naive，有的返回 aware，前端拿到后还要自己猜。排查这类问题最费时间，因为错误往往出现在比较和运算那一行，但根源在很远的地方。
我的建议是，在项目里加一个显性约定：所有跨服务传递的时间必须带时区。如果确实要传 naive 时间，必须通过接口文档明确说明它是哪个时区下的。任何datetime.now()都带上timezone.utc，任何从第三方库返回的本地时间都立刻标记出它对应的时区。
5.2 月末、年末、闰年的计算陷阱
有人觉得闰年判断还能有什么坑，不就是一个year % 4 == 0吗？可实际规则是"四年一闰，百年不闰，四百年再闰"。比如 1900 年不是闰年，2000 年是闰年，2100 年不是闰年。真要稳定判断，直接用标准库：
import calendar print(calendar.isleap(2024)) # True另一个常见需求是"获取某月的最后一天"。请不要用"下个月 1 号减 1 天"这种自己推的算法，直接用calendar.monthrange(year, month)返回的该月天数和第一天的星期几：
import calendar year, month = 2025, 2 days_in_month, first_weekday = calendar.monthrange(year, month) print(days_in_month) # 28，2025 年不是闰年这种函数式写法比手写逻辑要稳得多。
5.3 毫秒、微秒与精度丢失
Python 的datetime只能精确到微秒，但很多外部系统给的精度是毫秒甚至纳秒。如果你用浮点数时间戳去转换，可能会因为二进制浮点的精度问题丢掉低位的数字。
核心场景有这几个：
- 从数据库读毫秒级时间戳时，别用
1000.0去乘除然后在 float 里来回倒腾。 - 如果系统对时间精度要求高，直接用
time.time_ns()拿纳秒级整数，或者用datetime对象承载微秒字段。 - 给外部系统的接口文档里明确写清楚精度单位，避免两边各换算一次导致精度漂移。
5.4 并发与缓存场景下的时间一致性
服务器集群中的多台机器，系统时间如果不同步，基于"当前时间"的调度任务就会出现重复执行或者漏执行。这个问题不是 Python 层面能解决的，但代码层面可以做防御：所有定时任务、缓存过期时间，尽量用统一的时钟源，比如数据库主库的时间或专门的时间服务。
还有一点是，datetime.now()在测试环境里可能会被测试框架 mock 掉，如果你在缓存 key 里拼时间，要注意 key 的一致性问题。生产环境里用 NTP 做时间同步是最基本的，否则你写的任何基于时间的逻辑都不可靠。
5.5 单元测试里怎么冻结时间
最后是一个提升幸福感的小技巧：写日期时间相关逻辑的单元测试时，不要让测试依赖真实的当前时间。否则你今天跑过了，到了下个月或者换了时区的 CI 机器上，测试就崩了。
我推荐在测试里固定一个时间基准，手动替换掉所有datetime.now()、datetime.utcnow()的调用点。更省事的做法是用第三方库把时间冻结住，比如freezegun，允许你在测试装饰器上指定"当前时间"：
from freezegun import freeze_time from datetime import datetime @freeze_time("2025-06-01 12:00:00") def test_my_logic(): now = datetime.now() assert now.year == 2025这样不管今天真实日期是哪天，测试结果都可复现。处理和时间相关的代码，可复现性比什么都重要。
我自己写日期时间代码时，最深的体会是：这门东西表面上是 API 调用问题，本质上是建模问题。只要一开始没想清楚"这个时间表示的是墙钟时间还是绝对时间""数据落库时应该存什么"，后面一定会有 Bug 找上门。先把 naive、aware、UTC、IANA 时区这套基本框架装进脑子里，再写代码，你会发现日期时间其实也没那么可怕。
