Go encoding/csv CSV 中字段数量不一致时怎样保留坏行

导入 CSV 时，最容易误判的一类错误是 record on line n: wrong number of fields。这不代表整份文件不可读：encoding/csv 的 Reader.Read 会把当前记录和字段数错误一起返回。做法是先保存返回的 record，再判断 err，把坏行放进隔离集合，正常行继续交给业务处理。

官方文档：https://pkg.go.dev/encoding/csv@go1.27.3#Reader

FieldsPerRecord 如何建立字段数基线

Reader 有三种策略。正数表示每条记录必须有指定数量的字段；零值会在第一次成功读到记录时采用它的字段数；负数则完全关闭字段数量检查。导入有固定列定义时，通常保留零值，让表头或第一条数据建立基线；如果第一行是表头，也要确认它确实和后续数据列数一致。

在 Read 循环里先保存坏行

不要写成“只要 err != nil 就跳过”。io.EOF 才表示读取结束；字段数异常和部分解析错误都可能带着可用的 record 返回。下面的代码把正常行和坏行分开保存，并为每条坏行附上偏移和解析位置。

package main

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

type badRow struct {
    Fields []string
    Line   int
    Column int
    Offset int64
    Err    error
}

func collectCSV(input string) ([][]string, []badRow, error) {
    reader := csv.NewReader(strings.NewReader(input))
    // 让首条记录确定字段数，后续少列或多列记录进入坏行集合。
    reader.FieldsPerRecord = 0

    var valid [][]string
    var badRows []badRow
    for {
        record, err := reader.Read()
        if err == io.EOF {
            break
        }

        // 默认不启用 ReuseRecord；复制一份也能明确隔离坏行的生命周期。
        fields := append([]string(nil), record...)
        item := badRow{Fields: fields, Offset: reader.InputOffset(), Err: err}
        var parseErr *csv.ParseError
        if errors.As(err, &parseErr) {
            item.Line = parseErr.Line
            item.Column = parseErr.Column
        }

        if err != nil {
            // 字段数量错误可留存后继续；其他解析错误也先隔离并记录。
            badRows = append(badRows, item)
            continue
        }
        valid = append(valid, fields)
    }
    return valid, badRows, nil
}

func main() {
    // 第二条少一列，第三条多一列；两条都会被保留。
    input := "id,name,score\\n1,Ada,98\\n2,Bob\\n3,Cyd,87,extra\\n"
    valid, badRows, err := collectCSV(input)
    if err != nil {
        panic(err)
    }
    fmt.Printf("valid=%d bad=%d\\n", len(valid), len(badRows))
}

这里用 errors.As 取出 ParseError，是因为字段数错误也会被包装在解析错误结构中；用 errors.Is(err, csv.ErrFieldCount) 可以进一步只识别字段数量异常。生产代码可以把 badRows 序列化到隔离文件，供人工修复，而不是把它们悄悄丢掉。

ParseError 和 InputOffset 怎样定位原始问题

ParseError.Line 与 Column 适合写入日志。列号按字节计数，不是 Unicode 字符数；多行引号字段还可能让 StartLine 与 Line 不同。InputOffset 是最近读完的记录末尾、下一条记录开头的输入字节偏移，适合在原始文件中切出上下文。

要注意：字段数错误和引号错误不是同一层问题。字段数错误通常仍有完整字段切片，可以由业务决定是否补空值；引号不闭合、裸引号等错误会返回部分记录，不能直接当作完整数据。只有在业务明确允许可变列时，才设置 FieldsPerRecord=-1；这只是取消数量检查，不会修复引号或分隔符错误。

把严格校验和坏行隔离放在同一层

建议把 CSV 读取层的结果分成“正常行、可定位坏行、不可继续的读取错误”三类。正常行进入数据库或后续转换；坏行至少保留原字段、行号、列号、偏移和错误文本；底层读取器本身失败时再终止批次。这样既不会因一条脏数据中断整批导入，也不会用宽松模式掩盖真实格式问题。

相关问题

FieldsPerRecord 设置为 -1 会自动修复 CSV 吗？

不会。它只关闭字段数量检查，少列、多列记录都可能被视为正常返回；引号和分隔符语法仍按 CSV 规则解析。

为什么不能只判断 errors.Is(err, csv.ErrFieldCount)？

因为引号错误、非法字段等解析错误也需要隔离，而且它们可能带着部分记录返回。实际循环应先处理 EOF，再统一记录非空错误。

InputOffset 能直接得到坏行的起始位置吗？

它表示当前记录结束与下一条记录开始的偏移。要取得当前行起点，应结合上一轮保存的偏移，或同时记录行号并从原始输入建立索引。

一句话落地：固定列 CSV 使用 FieldsPerRecord=0 或显式正数，循环中保留 record 与错误，再用 ParseError 和 InputOffset 给坏行留下可复查的证据。