Go Excelize Excel 日期数字与格式化日期有什么区别

在 Excel 里看到的“2026-10-13 09:30”和程序读到的 46308.3958333333，可能是同一个单元格的两种表现。前者是数字格式渲染后的结果，后者才是 Excel 保存日期时使用的序列数字。Excelize 不会把这两个概念自动合并成一个 Go 类型：读取时可以拿格式化字符串，也可以拿原始数字；需要真正的 time.Time 时，还要明确采用 1900 还是 1904 日期系统进行转换。

官方地址：https://github.com/xuri/excelize

先看懂 Excel 日期的两层含义

Excel 日期单元格通常由两个部分组成：一个浮点序列值和一个数字格式。整数部分表示从日期系统起点开始经过的天数，小数部分表示一天中的时间比例；例如 0.5 表示半天。yyyy-mm-dd、m/d/yy h:mm 等格式并没有改变底层数字，只决定这个数字在表格里如何呈现。

因此，导入程序首先要回答“我要用户看到的文本，还是要可计算的日期值”。做报表展示时，格式化字符串可能更方便；要排序、计算间隔、写入数据库或转换到业务时区时，应该保留序列值并转换为 time.Time。把格式化后的字符串直接当作日期数字继续计算，是最容易出现隐性错误的做法。

读取时，格式化日期和原始数字有什么区别

GetCellValue 的默认读取结果会考虑单元格的格式，所以同一个日期单元格可能返回带有日期样式的字符串。需要参与计算时，可以把 RawCellValue 设为 true，让结果尽量保持工作表里的原始值。下面的示例把两种读取目的放在一起，避免在调用点丢失语义：

package main

import (
    "fmt"
    "github.com/xuri/excelize/v2"
)

func readDateCell(f *excelize.File, sheet, cell string) error {
    // 默认读取用于展示，结果会根据单元格的数字格式返回。
    display, err := f.GetCellValue(sheet, cell)
    if err != nil {
        return fmt.Errorf("读取格式化日期: %w", err)
    }

    // 原始读取用于转换和计算，避免把显示文本当作序列数字。
    raw, err := f.GetCellValue(sheet, cell, excelize.Options{RawCellValue: true})
    if err != nil {
        return fmt.Errorf("读取日期序列值: %w", err)
    }

    fmt.Printf("显示值=%s，原始值=%s\n", display, raw)
    return nil
}

这里的“格式化”不是把值转换成了 Go 的 time.Time，而是让 Excelize 按单元格样式生成更接近表格显示的文本。反过来，原始读取也不代表已经完成日期转换，它通常仍需要解析成浮点数，再交给 ExcelDateToTime。

把序列数字转换成 time.Time 时要处理日期系统

Excel 工作簿常见两种日期系统：1900 系统和 1904 系统。Excelize 的 ExcelDateToTime 接收序列数字和一个布尔参数 use1904Format。这个参数描述的是工作簿采用哪种日期基准，不是“当前机器是否使用 1904 年”的开关。读取工作簿时，应该先读取工作簿属性，再把对应结果传给转换函数。

package main

import (
    "fmt"
    "strconv"

    "github.com/xuri/excelize/v2"
)

func serialToTime(raw string, use1904 bool) error {
    // 原始单元格值必须先按浮点数解析，不能解析格式化日期文本。
    serial, err := strconv.ParseFloat(raw, 64)
    if err != nil {
        return fmt.Errorf("日期序列值不是数字: %w", err)
    }

    // 第二个参数要和工作簿的 Date1904 属性保持一致。
    value, err := excelize.ExcelDateToTime(serial, use1904)
    if err != nil {
        return fmt.Errorf("转换 Excel 日期: %w", err)
    }

    fmt.Println(value.Format("2006-01-02 15:04:05"))
    return nil
}

1900 系统还有 Excel 历史兼容行为，不能把“序列数字直接加一个固定天数”当成通用转换策略。尤其是工作簿来自不同系统、模板或第三方导出器时，日期基准应以文件属性为准；如果只拿到一列数字而没有工作簿上下文，结果就不应被包装成无条件正确的日历日期。

写入 time.Time 后，显示格式仍然要单独决定

写入时的方向正好相反：SetCellValue 接收 Go 的 time.Time，Excelize 会把它保存为 Excel 可识别的日期数字，并为时间值设置默认日期样式。但“可以被 Excel 识别”和“正好符合业务显示要求”不是一回事。需要显示为纯日期、带秒时间或中文年月日时，应额外创建样式并绑定数字格式。

package main

import (
    "fmt"
    "time"

    "github.com/xuri/excelize/v2"
)

func writeDateCell() error {
    f := excelize.NewFile()
    defer func() {
        // 示例中释放工作簿资源；真实项目还要检查 Close 返回的错误。
        _ = f.Close()
    }()

    now := time.Date(2026, 10, 13, 9, 30, 0, 0, time.Local)
    if err := f.SetCellValue("Sheet1", "A1", now); err != nil {
        return fmt.Errorf("写入时间值: %w", err)
    }

    styleID, err := f.NewStyle(&excelize.Style{CustomNumFmt: stringPtr("yyyy-mm-dd hh:mm")})
    if err != nil {
        return fmt.Errorf("创建日期格式: %w", err)
    }
    // 数字格式只负责显示，不会把底层日期数字改成字符串。
    if err := f.SetCellStyle("Sheet1", "A1", "A1", styleID); err != nil {
        return fmt.Errorf("绑定日期格式: %w", err)
    }
    return f.SaveAs("dates.xlsx")
}

func stringPtr(value string) *string {
    // CustomNumFmt 要求指针，单独封装可以避免在调用处取临时变量地址。
    return &value
}

上例中的 time.Local 只是演示一个带位置的 Go 时间值；跨时区业务应先约定输入时区和落库时区，再决定表格展示时区。Excel 单元格本身并不替你保存完整的时区语义，格式化日期也不会自动解决时区转换问题。

按任务选择 API，不要混用三种值

可以用一句话记忆：格式化日期是“给人看的样子”，日期序列值是“给 Excel 计算的数”，time.Time 是“给 Go 业务逻辑用的类型”。Excelize 负责在这些表示之间提供 API，但不会替你猜测当前任务需要哪一层。

常见问题

为什么 Excel 里显示日期，GetCellValue 却读到数字？

通常是读取时启用了 RawCellValue，或者文件中的数字格式没有被识别为日期显示格式。先分别读取默认值和原始值，再根据任务决定是否转换。

把日期字符串用 time.Parse 转换可以吗？

可以处理已经确定布局的展示文本，但它依赖格式和地区设置。若需要保留 Excel 的数值语义，优先读取原始序列值，再使用 ExcelDateToTime。

SetCellValue 写入 time.Time 后为什么格式不是我想要的？

写入值和显示格式是两件事。为单元格绑定自定义数字格式，例如 yyyy-mm-dd hh:mm，即可控制展示；这不会改变底层日期值。

1904 日期系统应该在哪里确认？

不要根据某个数字猜测。应读取工作簿的日期属性，并把它对应到 ExcelDateToTime 的 use1904Format 参数；缺少工作簿上下文时，应该明确标记转换假设。