Go csv.ParseError 怎样定位 CSV 出错的行和列

我在处理供应商 CSV 导入时，最先遇到的不是“文件读不出来”，而是日志只显示了一句 parse error。真正要修数据时，必须知道记录从哪一行开始、在哪一行出错、列位置是多少。encoding/csv 已经把这些信息放进了 *csv.ParseError，关键是不要只打印原始错误字符串。

这篇只解决一个问题：解析失败后，怎样稳定取出 StartLine、Line、Column 和底层 Err，再生成导入日志能直接使用的诊断。

先分清三个位置字段

ParseError 的行列号从 1 开始，Column 是按字节计算的列位置。StartLine 表示当前 CSV 记录的起始行，Line 表示解析器发现错误的行。普通单行记录通常两者相等；字段允许换行时，两者可能不同。

因此，日志里只写 Line 不够：它能定位发现错误的物理行，却可能丢掉跨行记录的起点。排查坏引号时，两个字段应当一起保留。

用 errors.As 取出 ParseError

Reader.Read 返回的是普通 error 接口，不能直接把它断言成值类型。使用 errors.As 兼容包装后的错误，并单独处理 io.EOF：

package main

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

func main() {
	input := "id,name\n1,ok\n2,\"broken\n"
	r := csv.NewReader(strings.NewReader(input))

	for recordNo := 1; ; recordNo++ {
		record, err := r.Read()
		if err == io.EOF {
			break // 正常结束，不把 EOF 当成坏数据
		}
		if err != nil {
			var parseErr *csv.ParseError
			if errors.As(err, &parseErr) {
				fmt.Printf("第 %d 条记录失败：起始行=%d，错误行=%d，字节列=%d，原因=%v\n",
					recordNo, parseErr.StartLine, parseErr.Line, parseErr.Column, parseErr.Err)
				continue // 记录诊断后结束本次导入，避免把半条记录当成成功数据
			}
			fmt.Printf("第 %d 条记录遇到非 CSV 解析错误：%v\n", recordNo, err)
			break // 非 ParseError 交给上层处理
		}
		fmt.Printf("读取成功：%v\n", record)
	}
}

这里的 recordNo 只是程序读到的记录序号，不等于文件行号。多行字段会占用多行文本，所以定位文件时应以 ParseError 的三个字段为准。

把底层原因写进可读诊断

ParseError.Err 通常是 csv.ErrBareQuote、csv.ErrQuote 或 csv.ErrFieldCount。可以用 errors.Is 继续分类，也可以先把 parseErr.Error() 作为人类可读信息保存：

func describeCSVError(err error) string {
	var parseErr *csv.ParseError
	if !errors.As(err, &parseErr) {
		return fmt.Sprintf("非 CSV 解析错误：%v", err) // 先保留未知错误的原文
	}

	kind := "CSV 格式错误"
	switch {
	case errors.Is(parseErr, csv.ErrFieldCount):
		kind = "字段数量不一致"
	case errors.Is(parseErr, csv.ErrBareQuote):
		kind = "未加引号的字段包含裸引号"
	case errors.Is(parseErr, csv.ErrQuote):
		kind = "引号字段未正确闭合"
	}

	return fmt.Sprintf("%s：记录起始行 %d，错误行 %d，字节列 %d，详情：%v",
		kind, parseErr.StartLine, parseErr.Line, parseErr.Column, parseErr.Err)
}

如果日志要给运营人员看，可以把文件名、批次号和数据源标识放在函数外层拼接；不要把整行原始数据直接写入日志，避免把姓名、手机号等业务字段带进普通日志。

三个容易误判的边界

第一，字段数不一致同样会返回 ParseError，但它的错误描述重点是记录行，不一定有你期待的列号。第二，Column 是字节列，不是 Unicode 字符数；中文或其他多字节字符出现前后时，不能直接当作用户界面中的第几个字。第三，带换行的引号字段会让 StartLine 和 Line 分离，这不是行号计算错了，而是一次记录跨越了多行。

我最后保留的导入日志格式是：文件 + 记录序号 + 起始行 + 错误行 + 字节列 + Err 分类。这样既能让开发者回到原始文件定位，也不会把“读到第几条记录”和“文件第几行”混为一谈。

常见问题

为什么不能只打印 err.Error()？

默认文本能帮助人阅读，但结构化字段更适合日志检索、错误统计和后续定位，尤其是跨行记录。

ParseError 的 Column 是字符位置吗？

不是，它是从 1 开始的字节索引。需要展示给用户时，应结合原始编码和展示层规则再转换。

遇到 io.EOF 要不要记录为失败？

在循环读取中，io.EOF 表示正常读完文件，应与真正的 ParseError 分开处理。