Go encoding/csv 怎样处理字段数量不固定的记录

导入 CSV 时，最容易误判的一种情况是：第一条记录有 3 个字段，后面的记录有 4 个或 2 个字段，Go 却返回了 ErrFieldCount。这通常不是引号或逗号写错，而是 encoding/csv.Reader 的默认策略在帮你检查“每条记录是否和第一条一样长”。

如果业务允许每条记录的字段数不同，请在第一次调用 Read 或 ReadAll 之前设置 FieldsPerRecord = -1。如果字段数本来就有契约，则保留正数或默认的首条记录推断，并把错误交给上层处理。

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

下面的示例围绕一个边界展开：CSV 解析器负责拆字段，业务代码仍然要决定一条记录是否满足自己的最小字段要求。

为什么第二条记录会触发 ErrFieldCount

csv.NewReader 创建出来的 Reader 的 FieldsPerRecord 初始值是 0。这个值不是“永远不检查”，而是让第一次成功读取的记录决定字段数，后续记录必须保持一致。若设为正数，读取器会要求每条记录恰好拥有这个数量；只有负数才表示不检查字段数量。

因此，数据类似下面这样时，默认配置会在第二条记录处暴露不一致：

name,age,city
小林,28,杭州
小周,31,上海,研发组

这不代表 CSV 不能读取，而是当前 Reader 选择了“固定列数”语义。先确认数据协议，再决定是修正输入，还是显式允许可变字段。

FieldsPerRecord 设为 -1 才允许可变字段

可变字段文件的最小改法是在读取前设置负值。这个设置必须早于第一次读；读取器已经根据首条记录建立固定字段数后，再改变配置会让代码意图变得混乱。

package main

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

func readVariableFields(input string) error {
	reader := csv.NewReader(strings.NewReader(input))
	// 负值表示不检查每条记录的字段数量，适合可变列的输入。
	reader.FieldsPerRecord = -1

	for {
		record, err := reader.Read()
		if err != nil {
			// EOF 表示正常结束；其它错误仍要交给调用方处理。
			if err == io.EOF {
				return nil
			}
			return err
		}
		// 字段数不由解析器限制，业务层可按自己的最低要求判断。
		fmt.Printf("字段数=%d，记录=%v\n", len(record), record)
	}
}

生产代码中更推荐比较 err == io.EOF，而不是比较错误文本。上面的循环重点只在 FieldsPerRecord 的位置：它改变的是解析器的字段数策略，不会替你补齐缺失字段，也不会把额外字段自动合并。

如果每行至少需要两列，可以在拿到记录后自己判断：

// acceptRecord 只接受业务必需的两列，额外列保留给扩展数据。
func acceptRecord(record []string) (string, string, bool) {
	if len(record) 

Read 返回错误时，先保留记录再决定是否跳过

允许可变字段后，ErrFieldCount 不再是主要分支，但引号未闭合、非法转义等解析错误仍可能出现。单条调用 Read 时，返回值可能同时带有部分记录和错误；排障代码不要因为看到错误就把返回的字段直接丢掉。

package main

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

func consume(reader *csv.Reader) error {
	for {
		record, err := reader.Read()
		if errors.Is(err, io.EOF) {
			// 没有更多记录时正常结束读取。
			return nil
		}
		if err != nil {
			// 先记录 record，再按策略决定重试、跳过或终止。
			_ = record
			var parseErr *csv.ParseError
			if errors.As(err, &parseErr) {
				// ParseError 携带行列位置，适合写入导入诊断日志。
				return parseErr
			}
			return err
		}
		// 没有解析错误后，再把字段交给业务层做数量和类型检查。
		_ = record
	}
}

这里把“语法解析错误”和“业务字段不足”分开：前者来自 CSV 格式，后者来自你的数据契约。这样即使输入允许额外列，也不会把少关键列的记录静默写入数据库。

固定、首行推断和可变字段，按数据契约选择

FieldsPerRecord 的三个常见取值可以这样理解：

可变字段只解决“解析器是否因为列数不同而拒绝记录”，不解决列名映射、类型转换和缺失字段补默认值。落地时建议保留原始行号或导入批次号，在业务校验失败时能定位到具体记录；如果输入其实有固定协议，则优先修正数据或使用正数约束，让错误尽早暴露。

• 设置必须发生在第一次读取前。
• -1 不会补齐字段，也不会合并多余字段。
• 解析错误要保留 ParseError 的位置，业务缺列要单独记录。

相关问题

FieldsPerRecord 默认值是不是代表允许任意字段数？不是。0 会使用第一条记录的字段数作为后续检查基准。

设置 -1 后还需要检查字段数量吗？需要。解析器不检查列数后，应由业务代码判断最低字段、类型和必填值。

什么时候应该使用正数？当 CSV 来自固定接口、固定模板或需要严格导入时，正数能更早暴露数据契约破坏。

官方资料：https://pkg.go.dev/encoding/csv@go1.27.3、https://go.dev/src/encoding/csv/reader.go。本文配图为 ImageGen 生成的静态说明图，代码用于解释字段策略与错误边界，不把示例输出冒充为运行证据。