Go time.Time.UnixMilli 怎样转换毫秒时间戳

需要把 Go 的 time.Time 交给只接受毫秒时间戳的接口时，直接调用 t.UnixMilli() 即可。它返回一个 int64，表示这个时间点距离 1970 年 1 月 1 日 UTC 经过的毫秒数；时间对象带着什么 Location 不会改变这个结果。

官方地址：https://pkg.go.dev/time#Time.UnixMilli

最稳妥的约定是：领域层保留 time.Time，在进入 JSON、消息队列或数据库边界时统一调用一次 UnixMilli()；收到毫秒值后用 time.UnixMilli(value) 还原，不要再额外乘除 1000。

先分清 UnixMilli 返回的是什么

UnixMilli 的单位是毫秒，不是秒，也不是本地时钟读数。它描述的是一个绝对时间点，因此同一时刻分别用 UTC、上海或纽约时区展示，转换出的毫秒值仍然相同。变化的只是格式化显示，不是时间点本身。

不要因为变量名叫 timestamp 就默认它是秒。接口文档、数据库字段说明和消息协议必须明确写出单位，否则一个看似正常的整数可能会让时间偏移 1000 倍。

用一个小工具完成双向转换

下面的小程序把固定时间点转成毫秒，再用同一个毫秒值还原为 time.Time。代码重点是“只在边界转换一次”，而不是手动计算秒和纳秒。

package main

import (
    "fmt"
    "time"
)

func main() {
    // 使用 UTC 构造一个明确的时间点，避免示例受机器本地时区影响
    original := time.Date(2026, time.October, 22, 14, 30, 15, 123000000, time.UTC)

    // UnixMilli 返回自 Unix 纪元以来的毫秒数，类型是 int64
    milliseconds := original.UnixMilli()

    // UnixMilli 的包级函数按同一单位把毫秒值还原为 Time
    restored := time.UnixMilli(milliseconds).UTC()

    fmt.Println("毫秒值:", milliseconds)
    fmt.Println("还原时间:", restored.Format(time.RFC3339Nano))
}

这个程序的关键不是输出格式，而是两个 API 的单位对称：Time.UnixMilli 负责“时间点 → 毫秒”，time.UnixMilli 负责“毫秒 → 时间点”。如果对端接口使用秒，应改用 Unix，不要把毫秒值直接当秒传出去。

1970 年以前的时间为什么会得到负数

Unix 时间轴以 1970-01-01 00:00:00 UTC 为零点，所以 1969 年的时间天然会落在零点左侧，UnixMilli 返回负数。这不是溢出，也不需要先取绝对值。

package main

import (
    "fmt"
    "time"
)

func main() {
    // 这个时间点早于 Unix 纪元，因此结果应当是负毫秒数
    beforeEpoch := time.Date(1969, time.December, 31, 23, 59, 59, 500000000, time.UTC)
    milliseconds := beforeEpoch.UnixMilli()

    // 还原时继续使用毫秒 API，不能误换成 Unix 的秒参数
    roundTrip := time.UnixMilli(milliseconds).UTC()
    fmt.Println("纪元前毫秒值:", milliseconds)
    fmt.Println("还原时间:", roundTrip.Format(time.RFC3339Nano))
}

还要注意负数除法的直觉陷阱：如果业务需要把毫秒拆成秒和剩余毫秒，不要用浮点数再乘回去。优先保留原始 int64，或者让接收方直接支持毫秒字段。

接入 JSON 或数据库时只保留一个单位

如果 API 协议约定字段是毫秒，可以在 DTO 边界显式命名，例如 createdAtMs。这样比把 createdAt 留给调用者猜单位更安全。

type EventPayload struct {
    // 字段名直接写出 Ms，提醒调用方这里不是秒
    CreatedAtMs int64 `json:"createdAtMs"`
}

func newEventPayload(createdAt time.Time) EventPayload {
    // 只在出站边界转换一次，领域对象仍可继续使用 time.Time
    return EventPayload{CreatedAtMs: createdAt.UnixMilli()}
}

数据库也采用同样的原则：字段类型可以是有时区的时间类型，也可以是 BIGINT 毫秒值，但团队必须在 schema、接口文档和代码命名中保持一致。不要在写入前转一次、读取后又无条件乘 1000。

几个容易混淆的边界

• 时区不会改变 UnixMilli：它基于绝对时间点计算，Location 只影响展示。
• 精度会被截到毫秒：纳秒部分不足一毫秒的信息不会出现在返回值里，需要更高精度时选择 UnixMicro 或 UnixNano。
• 不要混用构造函数：time.Unix 的第一个参数是秒，time.UnixMilli 的参数是毫秒。
• 极端年份要遵守 int64 边界：官方文档对超出可表示范围的结果定义为 undefined，普通业务日期不应把它当作无限范围整数。

相关问题

UnixMilli 和 Unix 相差多少？

它们描述同一个 Unix 时间轴，但单位分别是毫秒和秒；数值通常相差约 1000 倍，不能直接互换。

time.Time 的时区不同，UnixMilli 会不同吗？

只要表示的是同一个时间点，结果不会因为 Location 不同而改变。改变的是格式化出来的本地时间。

毫秒值应该用 int 还是 int64？

标准库 API 返回 int64，跨平台或跨服务传递时也建议使用 int64，避免 32 位整数范围不足。

毫秒值转回时间应该怎么写？

使用 time.UnixMilli(ms)，若要按指定时区展示，再调用 In(location)，不要手动加减小时。

把时间点交给外部系统时，真正需要统一的是“单位契约”。Go 已经提供了成对的 UnixMilli API：出站调用一次 t.UnixMilli()，入站调用一次 time.UnixMilli(ms)，再用字段命名和文档明确这是毫秒，就能避开最常见的 1000 倍偏移。