time.mktime() 是 localtime() 的逆操作,將本地時間元組 (struct_time 或 9 元組) 轉換為 Unix 時間戳 (浮點秒數)。本文詳細說明其語法、參數、返回值、異常處理與實戰陷阱。
import time
timestamp = time.mktime(t)
struct_time 對象或長度為 9 的元組 (year, month, day, hour, min, sec, weekday, yearday, dst)OverflowError (超出平台時間範圍)、ValueError (無效日期如 2 月 30 日)| 索引 | 屬性 | 範圍 | 說明 |
|---|---|---|---|
| 0 | tm_year | 1970~2038 (32位) / 更廣 (64位) | 四位數年份 |
| 1 | tm_mon | 1~12 | 月份 |
| 2 | tm_mday | 1~31 | 日期 |
| 3 | tm_hour | 0~23 | 小時 |
| 4 | tm_min | 0~59 | 分鐘 |
| 5 | tm_sec | 0~59 | 秒 (允許 60 閏秒) |
| 6 | tm_wday | 0~6 | 星期幾 (0=週一) |
| 7 | tm_yday | 1~366 | 一年中的第幾天 |
| 8 | tm_isdst | -1, 0, 1 | 夏令時標誌 (-1=自動判斷) |
import time
# 構造 2009-02-17 17:03:38 (週二,第 48 天,無夏令時)
t = (2009, 2, 17, 17, 3, 38, 1, 48, 0)
secs = time.mktime(t)
print(f"time.mktime(t) = {secs:.6f}") # 1234915418.000000
# 驗證往復轉換
print(f"asctime(localtime(secs)) = {time.asctime(time.localtime(secs))}")
# Tue Feb 17 17:03:38 2009
time.gmtime() (UTC),結果會偏移時區差本地時間元組 → mktime → UTC 時間戳UTC 時間戳 → localtime() → 本地時間元組
# 同一壁鐘時間,DST 不同導致不同時間戳
t_dst_on = (2024, 7, 1, 12, 0, 0, 0, 183, 1) # 夏令時生效
t_dst_off = (2024, 1, 1, 12, 0, 0, 0, 1, 0) # 標準時間
print(time.mktime(t_dst_on) - time.mktime(t_dst_off))
# 差值不等於 182 天 * 86400,含 1 小時 DST 差異
建議: 設定 tm_isdst=-1 讓系統自動判斷,或使用 datetime 模組處理時區感知對象。
# 32 位系統 time_t 範圍:1901-12-13 ~ 2038-01-19
try:
time.mktime((2050, 1, 1, 0, 0, 0, 0, 1, 0))
except OverflowError as e:
print("32 位系統年份溢出:", e)
from datetime import datetime, timezone
# 本地時間轉時間戳 (Python 3.3+)
dt = datetime(2009, 2, 17, 17, 3, 38)
ts = dt.timestamp() # 自動處理本地時區
print(ts) # 1234915418.0
# UTC 時間轉時間戳
dt_utc = datetime(2009, 2, 17, 17, 3, 38, tzinfo=timezone.utc)
ts_utc = dt_utc.timestamp()
print(ts_utc) # 1234915418.0 (相同數值,但語義明確)
# 時間戳轉 datetime
dt_back = datetime.fromtimestamp(ts) # 本地時間
dt_utc_back = datetime.fromtimestamp(ts, tz=timezone.utc) # UTC
time.mktime() 是舊版 API,僅處理本地時間元組 → UTC 時間戳datetime,語義清晰、支援時區、無年份限制tm_isdst 與平台年份範圍理解時間表示的三重形式(元組、時間戳、datetime 物件)及其轉換關係,是處理定時任務、日誌分析、跨時區系統的基本功。