Go time.Parse 时间布局写对但解析失败怎么办

Go 里时间字符串解析失败，最容易误判的地方是把布局写成了其他语言常见的 YYYY-MM-DD。time.Parse 使用的是固定参考时间：Mon Jan 2 15:04:05 -0700 MST 2006。因此，布局看起来“意思对”，只要参考时间里的字符没有对应上，仍然会返回解析错误。

官方参考：https://pkg.go.dev/time

排查时先逐字符对照输入和参考时间，再单独检查时区。日期部分常见错误是把年份写成 YYYY，时间部分常见错误是把 24 小时制写成 03，时区部分则要区分 MST、-0700 和 Z07:00。如果输入没有时区，还要明确它应该按 UTC 还是某个业务地点解释。

先还原故障现场：布局并不是占位符模板

例如输入是 2026-10-17 19:30:05，正确布局应写成 2006-01-02 15:04:05。这里的 2006 表示四位年份，01 表示两位月份，02 表示两位日期，15 表示 24 小时制的小时。

可以把布局理解成“参考时间长什么样”，而不是“给字段起名字”。下面的静态说明图只展示字段关系，不是终端截图，也不是程序运行证据。

检查四组最容易写错的字符

第一组是年份。2006 是四位年份，06 是两位年份；YYYY 在 Go 布局里只是普通文本，输入中没有连续四个大写字母时就会失败。

第二组是月份和日期。01、1 分别对应零填充和不要求零填充的月份；02 是零填充日期，_2 表示空格填充的日期。不要把 MM 或 DD 当成 Go 的布局标记。

第三组是小时。15 表示 24 小时制，03 表示 12 小时制，后者通常需要配合 PM 或 pm。输入 19:30 时使用 03 会让布局与数值范围不一致。

第四组是文字和分隔符。布局里未被识别为参考时间字段的字符会按原样匹配。因此输入里的 T、空格、斜杠和括号都应与布局保留一致；它们不是可以随意省略的装饰。

用最小代码确认布局和错误位置

先保留原始错误，不要只打印一个空的时间值。*time.ParseError 中包含布局、输入以及解析器定位到的片段，适合用来判断是字段标记错了，还是分隔符、数值宽度不一致。

package main

import (
    "errors"
    "fmt"
    "time"
)

func main() {
    // 布局使用 Go 的参考时间，而不是 YYYY-MM-DD 占位符。
    layout := "2006-01-02 15:04:05"
    value := "2026-10-17 19:30:05"

    parsed, err := time.Parse(layout, value)
    if err != nil {
        // 保留 ParseError，便于定位布局与输入的第一个差异。
        var parseErr *time.ParseError
        if errors.As(err, &parseErr) {
            fmt.Printf("布局=%q 输入=%q 错误=%v\n", parseErr.Layout, parseErr.Value, parseErr)
        }
        return
    }

    // 这里的输入不含时区，Parse 会按 UTC 解释。
    fmt.Println(parsed.Format(time.RFC3339))
}

如果把布局改成 YYYY-MM-DD HH:MM:SS，程序会把这些字母当成必须出现在输入里的普通字符，错误就不是“年份值不对”，而是布局根本没有声明 Go 能识别的年月日字段。

时区写法要和输入形状完全对应

输入尾部是 Z 或 +08:00 时，布局应分别使用 Z07:00 这一组可选 UTC/偏移写法，或直接使用 -07:00 匹配数值偏移。输入是 UTC、CST 这类缩写时，布局中的对应标记通常是 MST。

数值偏移比缩写更适合作为跨系统协议字段，因为缩写可能存在歧义。更重要的是，布局只能描述输入形状；它不能替你猜测业务地区。

没有时区时区分 Parse 和 ParseInLocation

time.Parse 在输入没有时区信息时按 UTC 解释；如果业务约定字符串代表某个地点的当地时间，应传入明确的 *time.Location 使用 time.ParseInLocation。这不是布局错误，却经常和布局错误一起出现：解析已经成功，但转换后的时刻差了几个小时。

package main

import (
    "fmt"
    "time"
)

func main() {
    // 输入没有时区，先加载业务约定的地点。
    loc, err := time.LoadLocation("Asia/Shanghai")
    if err != nil {
        // 时区数据库不可用时应把错误交给调用方，而不是默默使用本地时区。
        panic(err)
    }

    layout := "2006-01-02 15:04:05"
    value := "2026-10-17 19:30:05"

    // ParseInLocation 让无时区输入落在指定地点，而不是默认 UTC。
    parsed, err := time.ParseInLocation(layout, value, loc)
    if err != nil {
        panic(err)
    }
    fmt.Println(parsed.Format(time.RFC3339))
}

如果输入本身已经包含 +08:00，优先让布局解析这个偏移；如果输入只有本地日期时间，再用 ParseInLocation 表达业务约定。不要先按 UTC 解析，再依赖机器的本地时区去“补救”。

按这张速查表收尾定位

相关问题

Go 的布局为什么必须使用 2006？

因为布局是参考时间的示例表达式，解析器用这些固定字符识别字段，不采用其他语言的占位符命名。

没有时区的时间一定要用 ParseInLocation 吗？

不一定。如果数据协议明确规定无时区即 UTC，使用 Parse 更直接；只有当它代表某个业务地点的当地时间时，才传入对应 Location。

为什么不建议直接使用 CST？

缩写在不同地区可能指向不同偏移。跨系统数据优先使用数值偏移或 RFC3339 形式，再根据业务需要转换 Location。