Python毫秒级时间戳获取全攻略：time模块精度与性能深度解析

1. 为什么毫秒级时间戳突然变成了必需品

先不急着写代码。做日志系统、写缓存失效策略、搞API限流的时候，你大概率会遇到一个场景：两个请求在同一个秒内进来了，如果用sleep(1)这种粗粒度去区分先后，结果就是后一个请求把前一个的缓存给覆盖了。我在给一个爬虫框架做去重队列时踩过这个坑，日志里两条记录时间完全一样，但顺序全乱了，最后排查到凌晨才发现是时间戳精度不够。

Python里最常用的time.time()返回的是浮点数秒，默认精度其实受系统限制，Windows下很多版本只能精确到毫秒左右，Linux下能到微秒量级。但如果你直接把time.time()当秒用，小数部分就被扔了，那你就直接把毫秒、微秒级别的信息量全部丢弃了。

再想一个场景：你在做性能基准测试，一段代码跑了0.0003秒，用time.time()前后相减，结果很可能就是0.0，因为浮点数的分辨率不够。这种时候毫秒级时间戳就成了刚需。日志排序、缓存过期、分布式ID生成、事件时序分析，这些都是毫秒时间戳的主战场。

顺便说一下，很多人第一次搜这个问题，其实是搜到了datetime模块的strftime，然后发现只能格式化到秒，折腾半天不知道%f能拿到微秒。这条路不是不行，但要拼接的代码更多，而且性能上比time模块差了不止一个数量级。如果你就是要在日志里记录一个带毫秒的时间字符串，datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')确实能用；但如果你要的是纯数字时间戳，用来做时间比较、排序、缓存key，那就得回到time模块来。

这篇文章就把time模块取毫秒时间戳这件事一次讲透：各种写法的区别、精度陷阱、性能对比、时区相关的坑，以及我实际项目里踩过的那些坑。

2. 先搞懂time模块和时间戳的基本原理

2.1 时间戳到底是什么

时间戳（Timestamp）本质上是从1970年1月1日00:00:00 UTC（Unix Epoch）到当前时刻经过的秒数。这个定义听起来简单，但它有三个关键点：

• 它是绝对时间，不带时区属性。无论你在北京、伦敦还是纽约，同一物理时刻的time.time()返回值完全相同。
• 它通常是浮点数，小数部分表示不足一秒的时间。
• 它的精度上限取决于操作系统和硬件时钟，而不是Python。

手册上写的是"返回自Epoch以来的秒数，以浮点数表示"，但这个浮点数的分辨率在Windows和Linux上是有差异的。Windows的time.time()底层调用GetSystemTimeAsFileTime，很多版本下只能提供毫秒级精度；Linux下调用gettimeofday或clock_gettime，可以提供微秒甚至纳秒级精度。

2.2 time模块里和当前时间相关的几个函数

Python的time模块里，获取当前时间相关的函数主要有三个，很多新手容易混：

time.time_ns()是Python 3.7才加入的，返回的是整数纳秒，不存在浮点数精度损失问题。这个函数是后面我们做毫秒时间戳的"大杀器"。

还有一点要提醒：time模块里还有一个time.monotonic()，它返回的是从某个不可指定的起点开始的单调递增时间，专门用来测时间间隔，不能用来做时间戳，因为它的相对起点是随机的。

2.3 为什么直接time.time()取不到"干净的"毫秒

很多人第一直觉是time.time()已经包含小数秒了，那直接乘1000不就行了？思路对，但要处理两个问题。

第一个问题是浮点数误差。time.time()返回的浮点数，在表示"当前秒数"这个量级时，IEEE 754双精度浮点数的分辨率大约在微秒量级（2.2e-16乘以秒数），这本身就限制了精度。第二个问题是取整策略——是四舍五入round()还是截断int()？这俩在临界值附近会差出1毫秒。后面我会单独讲这个坑。

3. 三种主流写法：毫秒时间戳的获取方案与取舍

3.1 方案一：int(time.time() * 1000)，最直观但隐藏浮点坑

import time current_ms = int(time.time() * 1000) print(current_ms)

这段代码是网上最常见、Stack Overflow高赞答案的写法。思路特别简单：time.time()得到秒，乘以1000就是毫秒，再用int()转成整数。

但这里有一个隐蔽的问题：乘法本身可能引入浮点误差。举个例子，如果当前时间是1700000000.1234567秒，乘以1000后理论上应该是1700000000123.4567，但这个结果在double浮点数里可能被表示成1700000000123.4568之类的近似值，再转int()截断，你可能得到的是1700000000123，但实际的小数部分对应的是1700000000123.4567毫秒。对于大多数场景这1纳秒级别的误差无所谓，但在极端精度要求下会被诟病。

更为关键的实际问题是：如果time.time()本身精度受限，这个写法拿到的毫秒值，精度上限不会超过平台给的时间精度。如果你的系统只能精确到10毫秒，那这个毫秒时间戳的最后一位永远是0。这一点想清楚了，你就能理解为什么有些服务器上的时间戳看起来"很整齐"，不是巧合。

性能方面，这个写法还不错，一次浮点乘法和一次类型转换，开销非常小。适用于绝大多数业务场景：日志记录、缓存key生成、排序、简单计时。

3.2 方案二：time.time_ns() // 1_000_000，精度拉满还无浮点误差

import time current_ms = time.time_ns() // 1_000_000 print(current_ms)

time.time_ns()返回的是整数纳秒，范围大概是1.7e18级别，完全在Python int的表示范围内。直接整除1_000_000就得到毫秒，不存在任何浮点中间环节，也不会丢失精度。

这个方案在Python 3.7+才能用。如果你在写新项目，或者项目有明确的Python版本要求，我强烈建议用这个。它的性能也比time.time() * 1000略好一点点，因为整数除法比浮点乘法加转换更快（虽然这个差异在绝大多数场景下可以忽略）。

用整除//而不是/再int()，有一个好处：整除本身就是向下取整，不用再转换一步，代码也干净。如果要的是微秒，就整除1000；如果要纳秒，直接用原值。

不过有一点要注意：time.time_ns()返回的整数太大，如果直接存到某些数据库的整型字段里会溢出。一般数据库的BIGINT是64位有符号整数，最大9.2e18，纳秒时间戳约1.7e18，还能存得下，但如果你的数据库字段是INT32，那存纳秒必炸，存毫秒也勉强（毫秒约1.7e12，超过INT32上限2.1e9）。这是一个需要和团队约定好的事情。

3.3 方案三：datetime.now() 系列，性能差但适合格式化输出

from datetime import datetime # 不带时区的本地时间 current_ms = int(datetime.now().timestamp() * 1000) # 带UTC时区 current_ms = int(datetime.now(timezone.utc).timestamp() * 1000) # 格式化输出，保留毫秒 formatted = datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f') # 微秒，取前3位就是毫秒

datetime.now().timestamp()内部会调用time.time()类似的逻辑，但由于要创建datetime对象、处理时区转换，性能开销是time.time()的几倍到几十倍。我在做高并发日志记录时实测过，用datetime版每秒能处理的日志条数明显低于用time版。

那什么时候用datetime？只有一种情况：你最终要的是一串格式化的时间字符串，而不仅仅是数字时间戳。比如日志里要写2025-01-15 10:30:45.123这种格式，那直接strftime('%Y-%m-%d %H:%M:%S.%f')更省事。但如果你拿的是毫秒时间戳再去转换格式，那完全可以让time模块做完所有事情。

3.4 三种方案对比速查表

4. 实操中的几个坑：精度、时区、性能与兼容性

4.1 浮点数取整的坑：int()和round()差出1毫秒

直接看一个例子：

import time t = 1700000000.1235 print(int(t * 1000)) # 1700000000123 print(round(t * 1000)) # 1700000000124 print(int(round(t * 1000))) # 1700000000124

int()是向零取整，也就是截断，直接把小数部分扔了。round()是四舍五入，但Python的round()用的是"银行家舍入"（Banker's Rounding），遇到0.5时取最近的偶数。这意味着round(2.5)得到2，round(3.5)得到4，这一点极其反直觉，不少人在这里翻车。

对于时间戳这种带误差的量，我建议统一用int()向下取整，因为时间戳本身是"已经过去的时间"，向下取整不会把未发生的时间算进来。而且int()的性能比round()好一点点，避免多余的判断分支。如果你想用四舍五入，记得写成int(round(x * 1000))，并且接受银行家舍入带来的1毫秒级别影响（在正常时间戳上，这个误差无伤大雅）。

4.2 时区问题：时间戳本身无时区，但格式化有时区

很多新人会纠结：time.time()返回的是UTC时间还是北京时间？答案是都不是，它返回的是一个纯物理时刻的秒数，不看时区。你在中国和美国同一时刻调用time.time()，得到的数值完全一样。

真正有时区问题的是格式化环节。看这个例子：

import time from datetime import datetime, timezone ts = time.time() print(datetime.fromtimestamp(ts)) # 本地时区时间 print(datetime.fromtimestamp(ts, timezone.utc)) # UTC时间 print(datetime.utcfromtimestamp(ts)) # 已废弃，直接用UTC时的datetime

fromtimestamp默认使用本地时区，如果你在服务器上存了一堆格式化字符串，后来发现服务器时区从UTC改成了北京时区，那么所有历史日志的本地时间显示都会偏移8小时。时间戳本身不会变，变的是格式化时的时区设定。

最佳实践是：存数据库时用整数毫秒时间戳，不存格式化字符串；要给人看的时候，到展示层再转成目标时区的字符串。如果非要存字符串，请一律存ISO 8601格式并带上时区偏移量。

4.3 性能实测：time.time_ns()最快，datetime最慢

我写了一段简单的性能测试，循环100万次，结果如下（Python 3.11，Linux x86_64）：

datetime方案比time方案慢了5倍以上。原因很简单：datetime.now()需要构造一个完整的datetime对象，包含年月日时分秒的分解计算，而time.time()只是读一次系统时钟。

这个性能差距在单次调用时完全感知不到，但如果你在循环里每秒要打几万条日志、生成几万个缓存key，积少成多就很吓人了。我的建议是：能不用datetime就不用，除非你真的需要格式化字符串。

4.4 跨平台精度差异：为什么Windows下毫秒末位总是0

Windows上time.time()的实现精度历史上只有毫秒级，而且因为是系统时钟通过共享内存方式读取，可能还带一点抖动误差。这意味着在Windows机器上，int(time.time() * 1000)的末一位甚至末两位经常是0，看起来"很不精确"。

Linux上time.time()底层是gettimeofday，精度能到微秒；如果你的系统是Python 3.7+，还可以用time.time_ns()直接拿纳秒。所以：

如果你在Windows上测试时发现毫秒时间戳精度不对，先别怀疑代码，大概率是操作系统时钟精度限制。另外，Windows的time.time_ns()也受底层实现限制，实际可能只有几毫秒到十几毫秒的粒度，这是物理层面的限制，不是Python能解决的。

4.5 不要用time.clock()，拥抱time.perf_counter()

如果你是为了测代码耗时来搜毫秒时间戳，那我要多嘴一句：纯测间隔，用time.perf_counter()，别用time.time()。

time.time()返回的是墙上时钟（wall clock），可能因为系统自动校时、手动改时间、NTP同步而发生跳变。比如你在测试中间NTP把系统时间往后调了1秒，用time.time()测得的时间间隔就会多出1秒，这是灾难性的。

time.perf_counter()返回的是系统性能计数器，精度最高，且包含休眠期间的耗时，适合做性能基准测试。如果要测代码执行时间，标准做法是：

import time start = time.perf_counter() # 你的代码 elapsed = time.perf_counter() - start print(f"耗时: {elapsed:.6f}秒")

注意perf_counter()是从任意起点开始的，只能用来算差值，不能当时间戳用。

5. 工程场景里的实际应用示例

5.1 日志系统：毫秒时间戳配合trace_id

这里给一个日志工具函数，我项目里在用的简化版：

import time import os import threading class Logger: def __init__(self, tag=""): self.tag = tag self._lock = threading.Lock() def log(self, msg): ms = time.time_ns() // 1_000_000 # 全局统一毫秒时间戳 thread_name = threading.current_thread().name pid = os.getpid() # 格式: 时间戳|进程ID|线程名|消息 print(f"{ms}|{pid}|{thread_name}|{msg}") logger = Logger("api") logger.log("request received")

这里有几个设计考虑：第一，全程只取一次时间戳，保证同一日志里所有字段对应同一个时刻；第二，用time.time_ns()而不是time.time()，精度更高且无浮点误差；第三，加锁避免多线程打日志时顺序错乱。日志文本里带上毫秒时间戳，后面排查问题时就很容易看出请求的先后顺序和间隔。

5.2 缓存Key生成：毫秒时间戳避免覆盖

写一个简单的缓存封装：

import time class SimpleCache: def __init__(self, expire_ms=5000): self._store = {} self._expire_ms = expire_ms def set(self, key, value): now_ms = time.time_ns() // 1_000_000 self._store[key] = (value, now_ms) def get(self, key): if key not in self._store: return None value, create_ms = self._store[key] now_ms = time.time_ns() // 1_000_000 if now_ms - create_ms > self._expire_ms: del self._store[key] return None return value cache = SimpleCache(expire_ms=100) cache.set("a", 1) time.sleep(0.05) print(cache.get("a")) # 5ms后还在 time.sleep(0.06) print(cache.get("a")) # 累计超过100ms后返回None

这里的核心是用毫秒级差值判断是否过期。如果你用秒级差值，那得拿time.time()相减，在毫秒级过期时间下几乎没法用。毫秒时间戳让SimpleCache能精确控制100毫秒的过期窗口，这在做接口限流、短期缓存时特别实用。

5.3 性能基准：用time_ns配合perf_counter

写一个可复现的性能测试工具：

import time def benchmark(func, *args, repeat=10000): # 先跑一遍，把指令缓存、JIT优化等预热 for _ in range(100): func(*args) times_ns = [] for _ in range(repeat): start = time.perf_counter_ns() func(*args) end = time.perf_counter_ns() times_ns.append(end - start) avg_ms = sum(times_ns) / len(times_ns) / 1_000_000 print(f"{func.__name__}: 平均耗时 {avg_ms:.6f} ms") def test_func(): time.time() benchmark(test_func, repeat=10000)

time.perf_counter_ns()是Python 3.7+提供的纳秒版本，比perf_counter()更精确且没有浮点误差。配合毫秒、纳秒单位，基准测试的结果输出非常直观。

6. 常见问题排查速查表

6.1 问题一：格式化时间字符串时毫秒丢掉了怎么办

import time from datetime import datetime ts = time.time() ms = int((ts - int(ts)) * 1000) # 取小数部分转为毫秒 time_str = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(ts)) + f".{ms:03d}" print(time_str) # 2025-01-15 10:30:45.123

.%03d一定要写，否则毫秒是1位或2位时长度不对，日志解析会出问题。也可以用datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]来拿到毫秒级字符串，但如前所述，会牺牲一点性能。

6.2 问题二：毫秒时间戳和秒级时间戳混用

团队协作时最恶心的事情是：后端用毫秒存，前端或用秒生成数据，两边叠加比对时数据对不上。解决办法只有一条：在项目里统一定义一个全局的时间戳生成函数，不允许任何人直接散写int(time.time() * 1000)。

# 全局工具模块 utils/time_utils.py import time def now_ms() -> int: return time.time_ns() // 1_000_000 def now_s() -> int: return now_ms() // 1000

以后所有人都从utils.time_utils里调，避免各写各的坑。

6.3 问题三：time.time_ns在旧Python版本不可用

如果项目还在用Python 3.6或更早，time.time_ns()是不存在的。检查一下版本：

import sys if sys.version_info >= (3, 7): current_ms = time.time_ns() // 1_000_000 else: current_ms = int(time.time() * 1000)

这种兼容写法虽然不太优雅，但在老系统上能救命。如果你真的频繁遇到这种兼容问题，建议尽早把Python版本升级上去，Python 3.7以下的版本已经停止官方支持，无论从功能还是安全角度都该升级了。

7. 我在实战项目里积累的几个关键心得

做这件事反复验证之后，我觉得最有价值的一个习惯是：统一在一个工具模块里封装时间戳函数，并且主干代码里只认整数毫秒。别管谁给你的接口是秒、是字符串、是datetime对象，进到你的核心逻辑时，必须是整数毫秒。用time.time_ns() // 1_000_000生成整型毫秒，这样最干净，没有浮点误差，没有时区歧义。

第二个心得是：不要为了精度去追求datetime的格式化能力。我早期写的日志代码，喜欢直接用datetime.now().strftime(...)来生成带毫秒的日志串，后来一减压测就发现瓶颈在日志字符串生成上。换成time.time_ns()取毫秒、再用算术运算拼接字符串之后，几十万行日志的生成时间明显下降。

第三个心得比较隐蔽：如果你在用print或者logging打日志，尽量确保整条日志里的时间戳是同一个时刻取的。我之前犯过错误，在方法开头取了一个时间戳，方法结束时又取了一个，结果日志里"开始"和"结束"两个时间戳来自不同时钟读取点，中间相差了好几十毫秒，查问题的时候特别困惑。正确做法是：一次日志调用只取一次时间戳，多用几次。

最后留一个可扩展的话题：如果你做的是分布式系统，需要全局递增ID、跨节点排序，那单机毫秒时间戳是不够的，还可能要引入逻辑时钟、雪花算法、物理时间戳+节点ID这些方案。但那是另一个话题了，单机场景下先把毫秒时间戳这个地基打好，一点也不亏。