DevToolbox
All articles

Unix时间戳完全指南：转换方法与常见坑

· 6 min read

在后端开发、日志分析、API 对接等场景中，Unix 时间戳几乎无处不在。然而，看似简单的时间戳在实际使用中却暗藏了不少坑——秒与毫秒的混淆、时区的隐性转换、2038 年问题……本文将系统梳理 Unix 时间戳的核心知识，并提供各主流语言的实用代码片段。

Unix 时间戳是什么

Unix 时间戳（Unix Timestamp），也称为 Epoch 时间或 POSIX 时间，是指从 1970 年 1 月 1 日 00:00:00 UTC（即 Unix 纪元，Epoch）到某一时刻所经过的秒数。

举个例子：

  • 0 对应 1970-01-01 00:00:00 UTC
  • 1000000000 对应 2001-09-09 01:46:40 UTC
  • 1748822400 对应 2025-06-02 00:00:00 UTC（约）

时间戳与时区无关——它始终是相对于 UTC 的绝对秒数，不受夏令时或本地时区影响。这正是时间戳被广泛用于跨系统时间存储和传输的根本原因。

秒与毫秒：最常踩的坑

Unix 时间戳原始定义以秒为单位，但许多现代系统和语言默认使用毫秒（千分之一秒）级时间戳。两者之间差了整整 1000 倍，混淆后会导致时间计算结果偏差 1000 年。

快速判断方法：看位数。

  • 10 位数字：秒级时间戳，例如 1748822400
  • 13 位数字：毫秒级时间戳，例如 1748822400000

JavaScript 的 Date.now() 和 Java 的 System.currentTimeMillis() 都返回毫秒级时间戳。Python 的 time.time() 返回秒级浮点数（小数部分即微秒）。在跨语言对接接口时，务必先确认时间戳的单位。

时间戳与日期互转代码

JavaScript

// 获取当前毫秒级时间戳
const msTimestamp = Date.now();           // 例如：1748822400000
const sTimestamp = Math.floor(Date.now() / 1000); // 秒级：1748822400

// 毫秒时间戳转 Date 对象
const date = new Date(1748822400000);
console.log(date.toISOString()); // '2025-06-02T00:00:00.000Z'

// 秒级时间戳转 Date 对象（需乘以 1000）
const dateFromSec = new Date(1748822400 * 1000);

// Date 对象转秒级时间戳
const ts = Math.floor(new Date('2025-06-02T00:00:00Z').getTime() / 1000);
console.log(ts); // 1748822400

Python

import time
from datetime import datetime, timezone

# 获取当前秒级时间戳（浮点数）
ts = time.time()           # 例如：1748822400.123456
ts_int = int(time.time())  # 取整：1748822400

# 时间戳转 datetime（本地时区，见下方时区说明）
dt_local = datetime.fromtimestamp(1748822400)

# 时间戳转 datetime（明确指定 UTC，推荐）
dt_utc = datetime.fromtimestamp(1748822400, tz=timezone.utc)
print(dt_utc)  # 2025-06-02 00:00:00+00:00

# datetime 转时间戳
dt = datetime(2025, 6, 2, 0, 0, 0, tzinfo=timezone.utc)
ts_back = dt.timestamp()
print(int(ts_back))  # 1748822400

Java

import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;

// 获取当前毫秒级时间戳
long msTimestamp = System.currentTimeMillis(); // 例如：1748822400000

// 毫秒时间戳转 Instant
Instant instant = Instant.ofEpochMilli(1748822400000L);

// 秒级时间戳转 Instant
Instant instantFromSec = Instant.ofEpochSecond(1748822400L);

// Instant 转 LocalDateTime（UTC）
LocalDateTime dt = LocalDateTime.ofInstant(instantFromSec, ZoneOffset.UTC);
System.out.println(dt); // 2025-06-02T00:00:00

// LocalDateTime 转时间戳（秒）
long ts = LocalDateTime.of(2025, 6, 2, 0, 0, 0)
    .toEpochSecond(ZoneOffset.UTC);
System.out.println(ts); // 1748822400

时区处理的坑

时区是时间戳转换中最容易出错的地方，尤其是在服务器部署于不同地区时。

Python 的隐患：datetime.fromtimestamp(ts) 在不传 tz 参数的情况下，默认使用运行机器的本地时区。如果你的开发机在北京（UTC+8），服务器在美国（UTC-8），同一时间戳会转出相差 16 小时的结果。正确做法是始终显式传入时区： 

from datetime import datetime, timezone, timedelta

# 明确指定 UTC（推荐存储和传输时使用）
dt_utc = datetime.fromtimestamp(1748822400, tz=timezone.utc)

# 明确指定北京时间（UTC+8）
beijing_tz = timezone(timedelta(hours=8))
dt_beijing = datetime.fromtimestamp(1748822400, tz=beijing_tz)
print(dt_beijing)  # 2025-06-02 08:00:00+08:00

JavaScript 的隐患：new Date(ts).toString() 会按浏览器或 Node.js 进程的本地时区格式化。如果要输出 UTC 格式，应使用 .toISOString() 或 .toUTCString()。在处理用户输入的日期字符串时，new Date('2025-06-02')（不带时间）在大多数 JavaScript 引擎中会被解析为 UTC 的 00:00:00，而 new Date('2025-06-02T00:00:00')（不带时区后缀）则被解析为本地时区的 00:00:00，两者可能相差数小时。

负数时间戳

Unix 时间戳可以是负数，表示 1970 年 1 月 1 日之前的时刻。例如：

  • -1 对应 1969-12-31 23:59:59 UTC
  • -2208988800 对应 1900-01-01 00:00:00 UTC

大多数现代语言都能正确处理负数时间戳，但部分旧版系统或数据库字段若使用无符号整数存储，则无法表示负值，在处理历史数据时需要特别注意。

2038 年问题

2038 年问题（又称 Y2K38）是指 32 位有符号整数在存储 Unix 时间戳时的溢出问题。32 位有符号整数的最大值为 2,147,483,647，对应的时间戳为 2038-01-19 03:14:07 UTC。超过这一时刻后，32 位整数会溢出变为负数，导致时间计算错误。

这个问题影响所有使用 32 位 time_t 类型的 C/C++ 程序，以及部分旧版 MySQL（TIMESTAMP 类型最大支持到 2038 年），而 64 位整数可以表示到约 2920 亿年后，完全不受影响。

解决方案：

  • 使用 64 位整数（int64/long/bigint）存储时间戳
  • MySQL 中用 DATETIME 类型替代 TIMESTAMP（后者受 2038 限制）
  • 确保操作系统和运行时已升级到 64 位版本

实际开发建议

基于以上分析，在实际项目中处理时间时，有以下几条通用原则值得遵守：

  1. 存储用整数，展示时再转换：数据库中将时间存为 BIGINT 类型的 Unix 时间戳（秒或毫秒），在业务层读取后再按需格式化为本地时间展示给用户。这比存储字符串格式的日期更利于排序、范围查询和跨时区处理。
  2. 统一内部传递格式：在服务内部（如函数参数、消息队列、缓存）统一使用秒级或毫秒级时间戳，并在团队内明确约定，避免混用。
  3. API 接口首选 ISO 8601：对外提供的 API 如果返回时间字段，建议使用带时区的 ISO 8601 字符串（如 2025-06-02T00:00:00Z），可读性好且无歧义，减少对接方出错的可能。
  4. 时区始终显式指定：不要依赖运行环境的默认时区，所有时间转换都应明确传入时区参数。
  5. 避免使用 32 位整数：新项目一律使用 64 位整数存储时间戳，避免埋下 2038 年问题的隐患。

总结

Unix 时间戳的核心是一个从 1970-01-01 00:00:00 UTC 起计算的整数，与时区无关。实际使用中最常见的问题是秒与毫秒的混淆（看位数：10 位秒，13 位毫秒）和时区的隐性转换（始终显式指定时区）。存储时使用 64 位整数，展示时再格式化——养成这个习惯，能避免绝大多数与时间相关的 Bug。

Try it free
Unix 时间戳转换工具
100% client-side · no signup · no upload
Open tool →