Go 写入 CSV 文件

当我们需要把程序里的表格数据导出为 .csv 文件供 Excel 打开查看时,可以使用标准库 encoding/csv 包中的 csv.NewWriter() 函数来实现。

向 CSV 文件写入数据主要有 2 种方式:一种是使用 WriteAll() 一次性写入整张表格,另一种是使用 Write() 配合 Flush() 一行一行地写入,正好与读取 CSV 文件时的 ReadAll() 和 Read() 一一对应。

WriteAll() 一次性写入

如果我们手头的数据已经整理成了一个 [][]string 类型的二维切片,最直接的做法就是使用 WriteAll() 方法。我们先调用 os.Create() 创建目标文件并传给 csv.NewWriter(),再调用 writer.WriteAll() 就能一次性把所有行写进文件中。

语法:

writer := csv.NewWriter(w)
err := writer.WriteAll(records)

说明:

csv.NewWriter(w) 接收一个可写入的文件对象并返回写入器 writer。随后调用 writer.WriteAll(records) 会将二维切片 records 中的所有行一次性写入文件,并且它会在内部自动调用 Flush() 将缓冲区的数据刷入硬盘,不需要我们再手动刷新。

示例 1:一次性导出 CSV 表格

package main

import (
    "encoding/csv"
    "fmt"
    "os"
)

func main() {
    // 创建目标 CSV 文件
    f, err := os.Create("export.csv")
    if err != nil {
        fmt.Println("创建文件失败:", err)
        return
    }
    defer f.Close()

    // 准备要导出的二维字符串切片
    data := [][]string{
        {"姓名", "年龄", "地址"},
        {"Jack", "20", "北京,朝阳"},
        {"Lucy", "18", "上海"},
    }

    // 创建写入器并一次性写入全部数据
    writer := csv.NewWriter(f)
    if err := writer.WriteAll(data); err != nil {
        fmt.Println("写入 CSV 失败:", err)
        return
    }

    fmt.Println("export.csv 导出成功")
}

运行结果如下。

export.csv 导出成功

分析:

writer.WriteAll(data) 会自动遍历二维切片 data 的每一行,在同一行的各个单元格之间加上英文逗号(,),并在每行末尾加上换行符。运行成功后,我们用记事本打开生成的 export.csv,可以看到如下内容:

姓名,年龄,地址
Jack,20,"北京,朝阳"
Lucy,18,上海

小伙伴们观察第 2 行可以发现,由于 "北京,朝阳" 本身包含英文逗号,csv.NewWriter() 在写入时自动帮我们在最外层包上了双引号。如果单元格里包含双引号或换行符,它同样会自动做好转义处理,不需要我们手动拼接引号,保证导出的表格列数不会错乱。

注意: 不管是 WriteAll() 还是下面要介绍的 Write(),都要求传入的每一个单元格必须是 string 字符串类型。如果我们要导出的年龄或分数原本是数字类型,需要先通过 strconv.Itoa() 或 fmt.Sprintf() 转换成字符串,再放进切片中。

Write() 与 Flush() 逐行写入

在实际项目中,待导出的数据通常并不是现成的 [][]string 二维切片,而是结构体切片或者从数据库里一条条读出来的记录。如果先把上万条数据全拼成二维切片再写,既繁琐又占内存。这时我们就可以调用 writer.Write() 方法,边转换边逐行写入。

语法:

err := writer.Write(record)
writer.Flush()
err := writer.Error()

说明:

writer.Write(record) 接收一个代表单行各个单元格的一维字符串切片 []string,先将其写入内存缓冲区。等所有行都写完之后,我们必须在最后手动调用一次 writer.Flush() 把缓冲区里的数据刷入磁盘,再通过 writer.Error() 检查刷盘过程中是否出错。

示例 2:逐行导出结构体切片

package main

import (
    "encoding/csv"
    "fmt"
    "os"
    "strconv"
)

type Student struct {
    Name  string
    Age   int
    Score float64
}

func main() {
    f, err := os.Create("students.csv")
    if err != nil {
        fmt.Println("创建失败:", err)
        return
    }
    defer f.Close()

    students := []Student{
        {Name: "Jack", Age: 20, Score: 95.5},
        {Name: "Lucy", Age: 19, Score: 88.0},
        {Name: "Tony", Age: 21, Score: 92.5},
    }

    writer := csv.NewWriter(f)

    // 1. 先写入表头行
    if err := writer.Write([]string{"姓名", "年龄", "成绩"}); err != nil {
        fmt.Println("写入表头失败:", err)
        return
    }

    // 2. 遍历结构体切片,动态转为字符串并逐行写入
    for _, stu := range students {
        row := []string{
            stu.Name,
            strconv.Itoa(stu.Age),
            fmt.Sprintf("%.1f", stu.Score),
        }
        if err := writer.Write(row); err != nil {
            fmt.Println("写入数据失败:", err)
            return
        }
    }

    // 3. 将内存缓冲区的数据刷入磁盘并检查错误
    writer.Flush()
    if err := writer.Error(); err != nil {
        fmt.Println("刷新出错:", err)
        return
    }

    fmt.Println("students.csv 写入完成")
}

运行结果如下。

students.csv 写入完成

分析:

在这个例子中,我们先调用 writer.Write() 写入表头,再在循环里把每个 Student 结构体的 Age 和 Score 转成字符串,拼成单行切片逐行写出。打开生成的 students.csv,可以看到如下内容:

姓名,年龄,成绩
Jack,20,95.5
Lucy,19,88.0
Tony,21,92.5

和 bufio.NewWriter() 一样,csv.NewWriter() 底层也是基于内存缓冲实现的。每次调用 writer.Write(row) 只是把当前这一行暂存到了内存缓冲区里,直到最后执行 writer.Flush() 时才会真正落盘。如果漏写了 Flush(),生成的文件打开就会是空的。

平时使用逐行写入时,小伙伴们不要图省事直接写成 defer writer.Flush()。

因为 csv.Writer 的 Flush() 方法本身没有返回值,用 defer 不仅容易忽略执行顺序,还会漏掉紧跟其后的 writer.Error() 检查。按上面的写法在末尾显式刷新并校验错误,才不容易丢数据。

常见问题

1. 为什么在 Windows 系统中直接用 Excel 双击打开生成的 CSV 文件,里面的中文会显示乱码?

因为 Go 语言默认使用 UTF-8 编码保存文件。中文版 Windows 上的 Excel 直接双击打开 .csv 文件时,容易误按本地的 GBK 编码去解析,导致中文变成乱码。

如果希望 Excel 直接双击打开也不乱码,我们可以在 os.Create() 创建文件后,先执行一行 f.WriteString("\xEF\xBB\xBF") 在文件开头写入 UTF-8 BOM 标识头。写完标识头之后,再调用 csv.NewWriter(f) 正常写入表格数据就可以了。

2. 如果不想覆盖旧文件,而是往已有的 CSV 文件末尾继续追加新行,应该怎么做?

示例中的 os.Create() 会清空已有文件,因此追加数据时不能使用它。我们可以改用 os.OpenFile("students.csv", os.O_WRONLY|os.O_CREATE|os.O_APPEND, 0644) 按追加模式打开文件。

拿到文件对象 f 后,我们把它传给 csv.NewWriter(f),此时不需要再重复写入表头行。直接调用 writer.Write() 写入新增的数据行,最后执行 writer.Flush() 并检查 writer.Error() 即可。

给站长反馈

绿叶网正在不断完善中,小伙伴们如果发现任何问题,还望多多给站长反馈,谢谢!

邮箱:lvyenet@vip.qq.com

「绿叶网」服务号
绿叶网服务号放大
关注服务号,微信也能看教程。
绿叶网服务号