Go csv.Reader 的 FieldsPerRecord 为 0 时为什么第二行列数不一致会报错

FieldsPerRecord 为 0 并不是关闭列数检查。它表示让 Reader 根据读到的首条记录确定字段数，后续记录必须保持相同列数。因此首条记录有三列、下一条只有两列时，Read 会报告 ErrFieldCount。允许变长记录要设为负数；已知业务固定三列，则在第一次读取前直接设为 3。

官方地址：https://pkg.go.dev/encoding/csv

调整范围：把零值推断改为明确的列数策略

这次需要调整的是导入程序的读取契约，不是依赖升级，也没有某个 Go 版本突然把零值改成严格模式。零值本身包含“由输入决定宽度”的语义。旧程序如果一直使用 NewReader 后直接 Read，却把零理解为不限制，就会在遇到不同宽度的记录时暴露问题。

先明确谁决定列数：固定模板由业务规范决定，来自多个来源但每份文件内部等宽的数据可以由首条记录决定，而天然允许变长的记录应交给应用逐条解释。这三类输入不能只用“解析成功就收下”来统一处理。

迁移范围应保持有限：确定 FieldsPerRecord 的值、设置时机，以及错误出现后记录是否进入业务层。不要为了让错误消失顺带改变分隔符、放宽引号语法或自动补列，否则容易把多个独立的输入规则混在一起。

三种配置怎样改变同一份输入的结果

正数模式从第一条记录开始就要求指定列数。零值模式依赖首条记录，因此一份从头到尾都只有两列的错误文件，可能满足“内部等宽”，却不满足业务规定的三列。固定模板选择正数，能把这两层契约对齐。

首条记录也会改变 Reader 中的 FieldsPerRecord：当零值推断出了三列，后面观察到的字段值便是 3。配置应在首次 Read 或 ReadAll 之前确定，不能期待同一个 Reader 对每条记录都重新推断。不同文件通常各用一个新 Reader，让每份输入有自己的读取状态。

旧代码为什么会把表头或空字段理解错

encoding/csv 不把表头当成特殊元数据。第一条读取结果即使写着 sku、name、qty，也是一条普通三字段记录。应用先 Read 一次拿走表头，仍然会建立零值模式的列数约束；“我已经跳过表头”不能撤销 Reader 已经保存的宽度。

还要区分物理行和 CSV 逻辑记录。完全空白的行会被忽略，而引号包裹的字段可以跨行，所以标题中的“第二行”在排查时应落实为第二条读取记录。只包含空格的行不能简单等同于空行。读者若直接按文本编辑器里的行号数逗号，可能得出错误结论。

空字段也算一列。例如 P-7,Notebook, 有三个字段，最后一个为空；P-7,Notebook 才是两个。引号中的逗号属于字段内容，不能用 strings.Split 代替 CSV 解析来计算字段数量。列数相同也不说明字段内容有效：数量字段为空，需要业务规则另行判断。

用完整示例区分列数错误和语法错误

下面的独立示例为三种策略分别创建 Reader，并把列数错误与其他解析错误分开。样例第二条数据缺少数量字段，最后一条数据恢复三列。本例在列数错误时报告并继续，以便观察后面的合法记录；实际导入也可以选择整份拒绝，但不要在未决定策略时直接使用错误记录。

package main

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

func inspect(input string, fields int) {
    // 每种策略使用独立 Reader，避免继承已经推断出的列数。
    r := csv.NewReader(strings.NewReader(input))
    r.FieldsPerRecord = fields

    for recordNo := 1; ; recordNo++ {
        record, err := r.Read()
        if err == io.EOF {
            return
        }
        if err != nil {
            if errors.Is(err, csv.ErrFieldCount) {
                // 列数错误仍返回该记录，但本例只报告，不交给业务处理。
                fmt.Printf("策略=%d 记录=%d 期望=%d 实际=%d 字段=%q\n",
                    fields, recordNo, r.FieldsPerRecord, len(record), record)
                continue
            }
            // 引号等解析错误单独处理，不当成列数问题放行。
            fmt.Printf("策略=%d 记录=%d 解析失败: %v\n",
                fields, recordNo, err)
            return
        }
        fmt.Printf("策略=%d 记录=%d 字段=%q\n",
            fields, recordNo, record)
    }
}

func main() {
    // 第一条是三列，第二条两列，第三条又恢复为三列。
    input := "sku,name,qty\nP-7,Notebook\nP-8,Folder,4\n"
    for _, fields := range []int{0, 3, -1} {
        inspect(input, fields)
    }
}

在列数不符的分支，Read 同时提供 record 字段和 err 状态，所以能够报告实际列数。错误会通过 ParseError 包装，使用 errors.Is 判断 csv.ErrFieldCount 比直接将整个 err 与哨兵错误比较更合适。语法错误可能只返回部分字段，因此示例遇到其他解析错误便停止，不拿它继续做业务映射。

这段代码是可独立阅读的示例，本文没有在本机执行。按输入与参数契约推导，0 和 3 会报告两列的那条记录；-1 不会对该记录报告列数不匹配，但也不会补出第三个字段。后续代码若无条件访问 record[2]，仍然有越界风险，变长模式必须自行检查所需索引。

迁移时该保留哪些回归样本

迁移固定模板时，保留表头三列、数据少一列、多一列、末尾空字段以及整份文件一致但只有两列的样本。最后一种尤其重要：它能区别“首条推断”与“固定三列”。再加入引号内逗号和跨行字段，确认业务没有把物理行或文本分隔符数量当作 CSV 字段数。

迁移到变长模式时，先写清必需字段的最小数量、额外字段的用途和缺省值来源，再把 FieldsPerRecord 改为 -1。关闭统一列数约束不会帮应用识别字段含义，也不会把缺列和空字段归成同一种业务状态。需要整份导入原子性时，还应在业务提交层决定何时接纳记录，而不是边读边无条件落库。

为什么读表头后字段值变成 3？因为零值模式已经使用首条记录完成宽度推断。表头在这个 API 中仍是记录。

设为 -1 能修复引号报错吗？不能。它只影响字段数量限制，引号语法是否符合 CSV 规则是另一件事。

列数错误后一定要丢弃整份文件吗？这由业务契约决定。可以拒绝整份、隔离错误记录或终止读取；关键是让错误记录的处置明确，避免有返回值就直接当成合格数据。

参考：Reader 官方文档；encoding/csv 官方实现。