Go CSV 为什么逗号字段错位

我在接一个“姓名、城市、备注”的 CSV 导入时遇到过一种很像业务错乱的问题：备注里明明写着“喜欢 Go, SQL”，读取后却多出一列，后面的字段全部右移。Go 并没有把逗号弄丢，真正的问题是这个逗号没有被 CSV 规则标记为字段内容。

官方资料：https://pkg.go.dev/encoding/csv

逗号为什么会把字段推偏

Go 的 encoding/csv 默认按逗号分隔字段，并支持 RFC 4180 风格的 quoted-field。下面这一行有三个字段，第三个字段里的逗号被双引号包住，所以不会产生第四列：

name,city,note
小明,北京,"喜欢 Go, SQL"

如果写成 小明,北京,喜欢 Go, SQL，解析器会按四个字段理解，这是输入格式的结果，不是 Reader 的随机错位。空白默认也是字段内容；仅仅给逗号两边加空格，并不能改变分隔关系。

这也是 strings.Split 容易制造问题的原因：它只看字符，不理解“引号内部的逗号仍属于当前字段”。同样地，字段内部换行和双引号也需要 CSV 解析规则，不能按行再简单切分。

用 encoding/csv Reader 读取带逗号的字段

读取时直接把输入交给 csv.NewReader。如果导入表头规定每行必须有三列，可以把 FieldsPerRecord 设为 3；如果第一行只是表头模板，也可以先读表头，再由它确定后续列数。

package main

import (
    "encoding/csv"
    "fmt"
    "io"
    "strings"
)

func main() {
    input := "name,city,note\n小明,北京,\"喜欢 Go, SQL\"\n"
    reader := csv.NewReader(strings.NewReader(input))
    // 固定三列；字段数变化时立即返回 ErrFieldCount。
    reader.FieldsPerRecord = 3

    for {
        record, err := reader.Read()
        if err == io.EOF {
            // EOF 只表示记录读完，不是导入失败。
            break
        }
        if err != nil {
            panic(err)
        }
        // 带逗号的备注会作为一个元素保留在 record[2]。
        fmt.Printf("%q\n", record)
    }
}

在这个例子里，record 仍然只有三项，第三项是 喜欢 Go, SQL。如果你的数据允许每行列数不同，可以设置 FieldsPerRecord = -1，但这只是关闭字段数检查，不会修复未加引号的逗号；业务层仍应决定哪些列是必需的。

用 FieldsPerRecord 和 ParseError 找到真正的坏行

“字段错位”有两种情况：输入本来合法，但调用方用错了拆分方法；或者输入确实缺少引号、出现裸引号或列数变化。固定列数后，先区分 ErrFieldCount、ErrBareQuote 和 ErrQuote，比打印一串切片更容易定位。

package main

import (
    "encoding/csv"
    "errors"
    "fmt"
    "io"
    "strings"
)

func readOne(input string) error {
    reader := csv.NewReader(strings.NewReader(input))
    // 先固定业务表的列数，让结构性错误尽早暴露。
    reader.FieldsPerRecord = 3

    _, err := reader.Read()
    if err == io.EOF {
        return nil
    }

    var parseErr *csv.ParseError
    if errors.As(err, &parseErr) {
        // ParseError 提供记录行、错误行和列号，适合写入导入日志。
        fmt.Printf("line=%d column=%d cause=%v\n", parseErr.Line, parseErr.Column, parseErr.Err)
        return err
    }
    return err
}

LazyQuotes 只能在确有兼容需求时使用：它允许部分不规范引号继续读取，但不会把一个未加引号的普通逗号变成字段内容。对于生产导入，通常更适合记录行号、拒绝坏行并修复上游生成逻辑。

生成 CSV 时让 Writer 自动处理逗号

手工拼接字符串是错位的另一来源。写出 CSV 时，csv.Writer 会根据字段内容自动增加必要的双引号并转义字段内部的双引号；调用 Flush 后还要检查 Writer.Error。

package main

import (
    "encoding/csv"
    "os"
)

func export(path string) error {
    file, err := os.Create(path)
    if err != nil {
        return err
    }
    defer file.Close()

    writer := csv.NewWriter(file)
    // Write 接收字段切片，逗号和双引号由 Writer 自动转义。
    if err := writer.Write([]string{"小明", "北京", "喜欢 Go, SQL"}); err != nil {
        return err
    }
    writer.Flush()
    // Flush 本身不返回错误，必须从 Writer.Error 读取底层写入结果。
    return writer.Error()
}

如果输入文件实际使用分号而不是逗号，可以设置 reader.Comma = ';'，但不要把它当成“逗号字段错位”的通用修复。分隔符必须和文件格式约定一致，并且是合法的单个 rune。

常见问题

为什么给字段加空格仍然会错位？

空格默认属于字段内容，不会改变逗号的分隔作用。必须用双引号包住包含逗号的完整字段。

FieldsPerRecord=-1 能解决错位吗？

不能。它只是不再检查每行字段数，未加引号的逗号仍会产生额外字段；固定格式导入更建议保留列数检查。

应该直接打开 LazyQuotes 吗？

不建议把它当默认开关。它适合兼容已存在的不规范引号，不能替代修复上游 CSV 生成逻辑，也可能让坏数据更晚暴露。