Python time模块获取当前时间戳并格式化为字符串

陈默

发布时间：2026-10-23 | 5人浏览过

原创

在 Python 开发中，获取系统当前时间并输出为诸如 2024-04-22 15:30:00 的人类可读格式，是记录运行日志、命名导出文件、记录业务操作节点时的基础需求。Python 标准库内置的 time 模块提供了与操作系统底层 C 运行环境紧密对齐的轻量级时间操作函数。通过 time 模块完成这一目标只需要清晰的三步：先用 time.time() 获取当前 Unix 时间戳，再用 time.localtime() 将该时间戳转换为结构化的本地时间元组 struct_time，最后通过 time.strftime() 按照自定义模板将其格式化输出为字符串。

一、三步核心流程解析

很多初学者容易产生一个误区：期望直接调用某个函数把浮点数秒数直接转化为日期字符串。在 time 模块的设计中，浮点秒数是一个纯粹的数值标量，缺乏年、月、日、时区等历法规则的几何投影。因此，转换必须严格经过中间结构体 struct_time。

Python time模块获取当前时间戳并格式化为字符串 — 图 1：time 模块将时间戳格式化为字符串的三步核心机制

下面是最典型且最直接的代码范例：

import time

# 步骤 1：获取当前 Unix 时间戳（以秒为单位的浮点数）
timestamp = time.time()
print(f"当前时间戳: {timestamp}")

# 步骤 2：将时间戳转换为本地时间的 struct_time 对象
time_struct = time.localtime(timestamp)

# 步骤 3：使用自定义模板格式化为字符串
formatted_str = time.strftime("%Y-%m-%d %H:%M:%S", time_struct)
print(f"格式化字符串: {formatted_str}")

运行结果示例：

当前时间戳: 1713771000.456789
格式化字符串: 2024-04-22 15:30:00

二、深入第一步：获取当前时间戳与理解其本质

执行 time.time() 会返回一个 Python float 类型数值。它表示自 Unix 纪元（1970 年 1 月 1 日 00:00:00 UTC）起至当前时刻所流逝的秒数。这个数值具备以下关键事实与限制：

时区中立性：时间戳记录的是全球唯一的绝对物理时刻。无论程序运行在东京（UTC+9）、北京（UTC+8）还是伦敦（UTC+0），在同一瞬间调用 time.time()，得到的秒数数值理论上是完全一致的。
精度表现：虽然返回值是浮点数，但其小数部分的精确度取决于宿主操作系统的时钟时基（Clock Tick）。在现代操作系统上，通常能提供微秒或更精细的内部精度。

三、深入第二步：本地时间与 UTC 时间元组分流

得到时间戳之后，需要将其转换为拥有离散时间分量（年、月、日、时、分、秒、星期等）的 struct_time 结构。在 time 模块中，提供了两个语义明确的核心函数：time.localtime() 与 time.gmtime()。

1. time.localtime([secs])

将时间戳转换为当前系统配置时区的 struct_time。如果不传 secs 参数，它会默认取当前系统时间戳（即等同于 time.localtime(time.time())）。

2. time.gmtime([secs])

将时间戳转换为 UTC（0 时区）的 struct_time。如果在国内服务器（UTC+8）运行，gmtime() 输出的 tm_hour 会比 localtime() 小整整 8 个小时。在编写微服务通信、向第三方跨国 API 传参或统一日志落盘时，必须根据接口约定明确区分这二者。

3. struct_time 包含的具体字段

转换生成的 struct_time 是一个命名的 9 元组，它可以通过属性名称访问，也可以像普通元组那样按索引访问：

索引	属性名	含义	数值有效范围
0	tm_year	四位数公历年份	例如 2024
1	tm_mon	月份	1 到 12
2	tm_mday	日（月中某天）	1 到 31
3	tm_hour	小时（24小时制）	0 到 23
4	tm_min	分钟	0 到 59
5	tm_sec	秒数	0 到 61（考虑润秒）
6	tm_wday	星期序号	0 到 6（0 代表周一，6 代表周日）
7	tm_yday	年内序号（第几天）	1 到 366
8	tm_isdst	夏令时标志	0（否）、1（是）、-1（未知）

四、深入第三步：使用 time.strftime 格式化与占位符速查

函数签名定义为：time.strftime(format[, t])。第一个参数是包含格式控制字符的模板字符串；第二个参数是可选的 struct_time 对象（若省略，默认使用 time.localtime() 的结果）。

常见应用场景示例

import time

t = time.localtime()

# 1. 国际通用标准 ISO 8601 风格
iso_str = time.strftime("%Y-%m-%d %H:%M:%S", t)
print(f"标准格式: {iso_str}")

# 2. 适用于日志文件命名（避免 Windows 路径中非法的冒号）
file_safe_str = time.strftime("%Y%m%d_%H%M%S", t)
print(f"文件名安全格式: {file_safe_str}")

# 3. 附带星期与时区信息
verbose_str = time.strftime("%Y年%m月%d日 %A %H:%M:%S (%Z)", t)
print(f"详细格式: {verbose_str}")

特别提醒：Windows 环境下包含中文格式符的报错避坑

在 Windows 操作系统的部分旧版 Python 运行时中，如果直接在 strftime 模板中写入非 ASCII 字符（如 "%Y年%m月%d日"），底层 C 运行时库（msvcrt）可能会抛出 UnicodeEncodeError。规避该问题的最佳跨平台写法是：使用英文字符格式化后，再利用 Python 自身的字符串 format() 填入中文：

time.strftime("%Y{y}%m{m}%d{d}").format(y="年", m="月", d="日")

五、实用进阶：毫秒时间戳的格式化与方案选型

1. time 模块如何支持毫秒（Millisecond）

time.strftime() 来自于 C 语言的 strftime 函数实现，它不支持微秒占位符 %f。如果业务场景（如高频量化交易日志、分布式追踪 traceId）必须精确到毫秒，最轻量的做法是利用 time.time() 的小数部分进行手动取余拼接：

import time

now_ts = time.time()
local_t = time.localtime(now_ts)

# 计算三位毫秒数值（取小数部分乘以 1000）
milliseconds = int((now_ts - int(now_ts)) * 1000)

# 拼接基础格式与毫秒值
formatted_ms = time.strftime("%Y-%m-%d %H:%M:%S", local_t) + f".{milliseconds:03d}"
print(f"精确到毫秒的时间: {formatted_ms}")

示例输出：2024-04-22 15:30:00.384

2. time.ctime() 的快速用法及其局限

如果只是在调试或命令行排查时需要快速查看时间，可以使用 time.ctime([secs])。它接收一个时间戳并直接返回固定格式的英文字符串：

print(time.ctime())
# 输出示例: Mon Apr 22 15:30:00 2024

它的局限非常明显：输出格式是固定的（与 C 标准 asctime 保持一致），完全无法调整年月日顺序或语言，因此正式业务中依然应当使用 strftime。

六、技术选型与最佳实践总结

归纳全文，使用 Python time 模块获取时间戳并格式化为字符串的核心要领包括：

牢记三步流转：time.time() 生成时间戳 ➔ time.localtime() 构建时间元组 ➔ time.strftime() 按模板输出。
明确时区归属：对外展示与本地日志使用 localtime()；跨系统数据交互与零时区存储使用 gmtime()。
掌握标准模板：牢记 "%Y-%m-%d %H:%M:%S" 的大小写规范（注意 %m 为月，%M 为分；%H 为 24 小时制，%I 为 12 小时制）。
评估性能与扩展性：在日志打点等高频简单场景下，time 模块内存与执行开销极小；当后续需求扩展到跨天时间差计算、复杂时区转换或原生微秒解析时，再适时切换至面向对象的 datetime 模块。