time

time.In

返回给定日期/时间在指定 IANA 时区中的表示。

签名
time.In TIMEZONE INPUT
返回类型
time.Time

这一页解决什么问题

同一个时刻在不同时区显示的时间不同。time.In 把已有的 time.Time 换算到指定时区再返回(仍是同一时刻,只是「表示」变了),通常紧接着交给 time.Format 输出。

它与 time.AsTime 的分工要分清:time.AsTime 的第二参数决定解析字符串时把没有时区的串当成哪个时区;time.In 是对已经确定时刻的值做换算。参数顺序是 时区在前、时间在后。

什么时候用,什么时候别用

该用:

  • 给不同地区的读者显示当地时间;
  • 把带数字偏移的时间先统一到某个具名时区,再格式化(也更容易拿到时区缩写,见 time.Format 的实测说明);
  • 需要按某个时区的日界线做「今天/昨天」判断。

别用:

  • 只想改显示格式、不改时区 → 用 time.Format;
  • 想把「没有时区的字符串」解释成某地时间 → 用 time.AsTime 的第二个参数;
  • 拿到的是字符串还没解析 → 先用 time.AsTime。

用法

(0.146.0 新增)

time.In 函数返回给定日期/时间在指定 IANA 时区中的表示。

  • 如果时区为空字符串或 UTC,时间以 UTC 返回。
  • 如果时区为 Local,时间以系统的本地时区返回。
  • 其它情况下,时区必须是有效的 IANA 时区名称。
go-html-template
{{ $layout := "2006-01-02T15:04:05-07:00" }}
{{ $t := time.AsTime "2025-03-31T14:45:00-00:00" }}

{{ $t | time.In "America/Denver" | time.Format $layout }}     → 2025-03-31T08:45:00-06:00
{{ $t | time.In "Australia/Adelaide" | time.Format $layout }} → 2025-04-01T01:15:00+10:30
{{ $t | time.In "Europe/Oslo" | time.Format $layout }}        → 2025-03-31T16:45:00+02:00

完整示例:同一时刻换算到四个时区

layouts/_partials/timezones.htmlgo-html-template
{{ $layout := "2006-01-02T15:04:05-07:00" }}
{{ $t := time.AsTime "2025-03-31T14:45:00-00:00" }}
<p>{{ $t | time.In "UTC" | time.Format $layout }}</p>
<p>{{ $t | time.In "America/Denver" | time.Format $layout }}</p>
<p>{{ $t | time.In "Australia/Adelaide" | time.Format $layout }}</p>
<p>{{ $t | time.In "Europe/Oslo" | time.Format $layout }}</p>
<p>空字符串(等同 UTC):{{ $t | time.In "" | time.Format $layout }}</p>

Hugo 渲染为:

html
<p>2025-03-31T14:45:00+00:00</p>
<p>2025-03-31T08:45:00-06:00</p>
<p>2025-04-01T01:15:00+10:30</p>
<p>2025-03-31T16:45:00+02:00</p>
<p>空字符串(等同 UTC):2025-03-31T14:45:00+00:00</p>

你应当看到什么:五行表示的是同一个时刻(UTC 的 14:45),只是各地读数不同;Australia/Adelaide 已经跨到第二天(04-01);空字符串按 UTC 处理。

返回值边界(实测)

测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN',timeZone = 'Asia/Shanghai'),Windows。

情况 结果 是否报错
时区为空字符串 按 UTC 返回(实测 +00:00) 否
时区为 UTC 按 UTC 返回(实测 +00:00) 否
时区为 Local 按系统本地时区返回(实测在 Asia/Shanghai 机器上为 +08:00) 否
时区名无效(Bad/Zone) —— 是:error calling In: unknown time zone Bad/Zone
输入是字符串(不是 time.Time) —— 是:can't handle "2025-03-31T14:45:00Z" for arg of type time.Time,需先用 time.AsTime 解析
返回类型 time.Time(同一时刻,仅表示不同) 否

常见坑

类别 症状 真因 怎么修
报错看不懂 unknown time zone Bad/Zone 时区名拼错或不在 IANA 数据库 用标准名,如 Asia/Shanghai、Europe/Oslo
没报错但结果不对 换算后时间没变 该时刻本来就属于该时区,或忘了接 time.Format 看结果 用 time.Format 指定布局输出后再核对
没报错但结果不对 输出带的是缩写而非偏移 具名时区才可能给出缩写;带数字偏移的输入不会 想稳定显示请用 -07:00 这类偏移布局(见 time.Format)
报错看不懂 参数顺序报错 写成了「时间在前」 记牢 time.In TIMEZONE INPUT,或用管道:$t | time.In "…"

更多排查入口见故障排查。