Go CSV 不等长字段错误的 Reader 配置

CSV 导入最容易让人误判的一类报错，就是同一个文件里有些行是 3 列，有些行是 4 列，Go 的 encoding/csv.Reader 却返回了 wrong number of fields。这个问题通常不需要换库，关键是先决定：文件应该严格保持固定列数，还是确实允许缺列、扩列。

Go CSV 的字段数策略由 Reader.FieldsPerRecord 决定：正数表示严格要求固定列数，0 表示以第一条记录建立基准，负数表示不检查字段数。要接收不等长记录，直接设为负数，再把缺失字段和多余字段交给业务层处理。

• 想让每行都和表头一致：使用正数，或保留默认的 0 并检查 ErrFieldCount。
• 想兼容历史文件的缺列、扩列：设置 FieldsPerRecord = -1。
• 想知道是哪一行出问题：保留 *csv.ParseError，不要只打印一段字符串。
• 字段数量不一致和引号没有闭合是两类错误，不能用同一个开关混在一起处理。

先看清 Reader 为什么会报字段数错误

我在做一个小型 CSV 清洗命令时，输入文件的第一行是表头，后面的历史数据来自不同导出系统。只要第一条数据行比表头少一列，循环就会在读取时出现 ErrFieldCount。这不是逗号本身解析失败，而是 Reader 正在执行字段数量约束。

官方文档把 FieldsPerRecord 分成三种语义：大于 0 时每条记录都必须有指定数量的字段；等于 0 时第一次调用 Read 会把该记录的长度写回 Reader，后续记录沿用这个基准；小于 0 时不做字段数量检查。默认值是 0，所以“看起来没有配置”并不等于“不检查”。

用负数配置读取不等长 CSV

如果文件格式本身允许缺列或扩列，可以把字段数检查交给清洗逻辑。下面的示例把第一列当作订单号，第二列当作状态；少于两列的行记录为异常，多出来的字段先保留在切片中，便于后续决定是否入库。

package main

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

func main() {
    input := "order_id,status,note\nA-001,paid\nA-002,shipped,from-legacy\n"
    reader := csv.NewReader(strings.NewReader(input))
    // 负数表示不校验每条记录的字段数量，适合先接住历史数据。
    reader.FieldsPerRecord = -1

    for line := 1; ; line++ {
        record, err := reader.Read()
        if err == io.EOF {
            // 到达文件末尾是正常结束，不当作失败。
            break
        }
        if err != nil {
            // 语法解析错误仍然要停止，不能把坏行当成普通缺列。
            panic(fmt.Errorf("第 %d 行解析失败: %w", line, err))
        }
        if len(record) 

这里的重点不是“忽略错误”，而是把检查位置从 Reader 移到了业务层。FieldsPerRecord = -1 只关闭字段数量检查；如果某一列的引号没有闭合，Read 仍会返回解析错误。对历史导入来说，这样可以同时保留完整原始行和自己的补齐、跳过策略。

需要严格结构时，直接固定字段数量

如果 CSV 是接口契约或数据库导入文件，缺一列往往比多一列更危险。这时可以明确配置字段数，例如表头加两列数据共 3 个字段。严格模式的好处是错误尽早暴露，代价是调用方必须决定如何记录和展示异常行。

package main

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

func main() {
    input := "order_id,status,note\nA-001,paid\nA-002,shipped,from-legacy\n"
    reader := csv.NewReader(strings.NewReader(input))
    // 正数要求每条记录都有 3 个字段，适合固定格式的导入协议。
    reader.FieldsPerRecord = 3

    for {
        record, err := reader.Read()
        if err == io.EOF {
            // 正常读完后退出循环。
            break
        }
        if errors.Is(err, csv.ErrFieldCount) {
            // 记录仍可能返回，先保存长度和内容，方便定位坏行。
            fmt.Printf("字段数异常：长度=%d 内容=%v\n", len(record), record)
            continue
        }
        if err != nil {
            // 非字段数错误通常是 CSV 语法问题，应按解析失败处理。
            panic(fmt.Errorf("CSV 解析失败: %w", err))
        }
        fmt.Printf("合法记录：%v\n", record)
    }
}

需要注意，字段数量错误通常会同时返回已经读出的 record 和错误值，因此可以把行内容写入错误记录，但不能把它当成合法业务数据继续落库。若采用默认值 0，则第一条读到的记录会决定后续基准；想固定契约时使用正数更直观。

把“补齐”放在业务层，不要让 Reader 猜含义

不等长并不天然代表错误。例如历史文件省略了末尾的备注列，业务可以把它解释为空字符串；但如果中间的状态列缺失，直接按位置补齐就可能把数据写错。推荐先保留原始切片，再根据列名或业务规则生成目标对象。

func normalize(record []string) (map[string]string, error) {
    if len(record) = 3 {
        // 末尾字段存在时才覆盖默认空值，兼容旧格式文件。
        result["note"] = record[2]
    }
    return result, nil
}

这种处理方式让“少一列怎么办”成为可审计的业务决定：必需字段缺失就拒绝，末尾可选字段缺失就补默认值，多出的字段则可以记录在原始数据或异常表中。不要为了让循环继续而无条件截断字段。

字段数错误和 CSV 语法错误不是一回事

ErrFieldCount 说明记录字段数和预期不一致；例如严格模式期待 3 个字段，但实际只有 2 个。未闭合引号、非引号字段中出现不允许的引号等问题，则属于 CSV 语法解析错误。前者可以由业务规则选择放宽，后者通常需要修复输入或明确启用与格式匹配的解析选项。

如果需要判断具体行和列，可将错误断言为 *csv.ParseError，读取它的 StartLine、Line 和 Column。对于多行引号字段，错误所在的物理行和记录起始行可能不同，这也是只打印 err.Error() 不够时应该保留结构化错误的原因。

最后用这张表选择配置

最终判断可以压缩成一句话：格式是契约就严格配置，格式是历史事实就宽松读取、业务判断；无论选择哪一种，都不要把引号解析失败误当成普通缺列。这样既能保留导入效率，也能让异常行在后续追溯时有明确的原因。

常见问题

FieldsPerRecord 设为 0 是不是允许任意字段数？

不是。0 会让第一条成功读取的记录建立字段数基准，之后的记录仍按这个数量检查。不等长文件应使用负数，或在严格模式下显式处理 ErrFieldCount。

FieldsPerRecord 设为 -1 后还会出现错误吗？

会。它只关闭字段数量检查，未闭合引号、非法引号等格式问题仍可能产生解析错误；另外底层读取器的 I/O 错误也不会被忽略。

出现 ErrFieldCount 时 record 一定是 nil 吗？

不一定。字段数错误通常会返回已经解析出的记录和错误值，所以可以保存这条记录用于排查，但不能在未补齐或审核前把它当成合法对象。

能不能用 LazyQuotes 解决不等长字段？

不能把两者混为一谈。LazyQuotes 针对某些引号写法的宽松解析，FieldsPerRecord 针对字段数量约束；先判断错误类型，再选择对应配置。