Go CSV 多行字段报错时怎么用 FieldPos 定位到真实列号

我第一次遇到 CSV 多行字段报错时，日志里的“第 4 行第 9 列”看起来像是下一条记录，但把原始文本展开后才发现：上一条记录的引号字段跨了物理行。这里真正要区分的是逻辑记录和物理行。Go 的 encoding/csv 已经提供了 Reader.FieldPos，可以在记录读出来之后，按字段索引拿到该字段起点的 1-based 行号和字节列号。

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

处理多行 CSV 时，不要用“读了几条记录”推算错误位置。先让 Read 给出解析结果，再用 FieldPos(field) 定位字段；如果是语法错误，则同时读取 ParseError 的错误范围。

本文只讨论标准库解析器支持的带引号多行字段，不讨论自定义 CSV 语法或自行编写扫描器。

为什么多行字段会让日志行号看起来错位

CSV 的引号字段可以包含换行符。对解析器来说，换行并不一定意味着一条记录结束；对日志阅读者来说，文本中的每个换行却都会增加物理行号。于是“第 2 条记录”可能从物理第 3 行开始，在物理第 5 行才结束。

字段索引也要单独看待：Read 返回的切片索引从 0 开始，FieldPos 接收的正是这个字段索引；它返回的行号和列号则从 1 开始。下面这张图是静态结构说明，不是运行截图：

先用 Read 判断是记录结束还是解析失败

正常情况下，Read 返回一条完整记录；读完输入后返回 io.EOF。如果引号没有闭合、字段结构不符合解析规则，则返回一个 *csv.ParseError。它记录的是解析错误的起始行、出错行和字节列，不应和某个已返回字段的起点混为一谈。

package main

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

func readCSV() error {
	input := "id,note\n1,\"第一行\n第二行\"\n2,ok\n"
	reader := csv.NewReader(strings.NewReader(input))

	for {
		record, err := reader.Read()
		if errors.Is(err, io.EOF) {
			// EOF 表示没有下一条逻辑记录，不是解析错误。
			return nil
		}
		if err != nil {
			var parseErr *csv.ParseError
			if errors.As(err, &parseErr) {
				// ParseError 的 Column 是字节列，描述错误范围。
				return fmt.Errorf("CSV 解析失败：起始行=%d，错误行=%d，字节列=%d：%w", parseErr.StartLine, parseErr.Line, parseErr.Column, err)
			}
			return fmt.Errorf("读取 CSV 失败：%w", err)
		}
		fmt.Printf("记录字段数=%d\n", len(record))
	}
}

这段处理的关键是先分支 io.EOF，再用 errors.As 取出 ParseError。解析错误发生时，未必有一条可供业务继续使用的完整记录，所以不要在错误分支里盲目调用 FieldPos。

用 FieldPos 定位已经读出的字段起点

当 Read 成功返回记录后，字段切片中的每个位置都对应一个字段。对这些字段调用 FieldPos，返回值是该字段起点的物理行号和字节列号。多行字段的后续内容可能在下一行，但字段本身的起点仍然是第一个引号或字段内容开始的位置。

func printFieldPositions(input string) error {
	reader := csv.NewReader(strings.NewReader(input))
	for recordIndex := 0; ; recordIndex++ {
		record, err := reader.Read()
		if errors.Is(err, io.EOF) {
			// 所有逻辑记录都已读取完成。
			return nil
		}
		if err != nil {
			return err
		}

		fmt.Printf("逻辑记录=%d，字段数=%d\n", recordIndex, len(record))
		for fieldIndex, value := range record {
			line, column := reader.FieldPos(fieldIndex)
			// line 从 1 开始，column 是字节列，不是 Unicode 字符数。
			fmt.Printf("字段=%d，行=%d，字节列=%d，值=%q\n", fieldIndex, line, column, value)
		}
	}
}

FieldPos 的字段参数必须是本次返回记录中的有效索引，传入负数或超出范围的索引会触发 panic。因此日志代码应遍历当前 record，不要把外部配置里的列号未经检查直接传入。

中文字段为什么让列号和字符数不同

FieldPos 返回的是字节列号。UTF-8 中文通常占多个字节，所以某字段前面只要出现中文，字节列就可能大于肉眼看到的字符位置。这个设计适合和原始输入的字节偏移、解析器源码位置对齐，但不适合直接当作“第几个汉字”。

如果产品日志还需要面向用户展示字符位置，可以在拿到原始物理行后，另行把字节列转换为 UTF-8 字符边界；但应保留标准库给出的原始字节列，方便工程排查。不要把 len([]rune(line)) 的结果回写成 FieldPos 坐标。

把一次排查经验固化成日志格式

我后来把 CSV 错误日志固定为“逻辑记录索引、字段索引、物理行、字节列、原始错误”五项。这样既能让业务人员按记录索引理解问题，也能让开发者回到原始文件按物理行和字节列复查。对成功读取的记录，字段位置来自 FieldPos；对失败的记录，位置来自 ParseError，两类来源分别标记。

这样处理后，标题里所说的“真实列号”就有了明确含义：它是原始 CSV 物理行中的字节列，不是逻辑记录序号，也不是中文字符数量。

常见问题

FieldPos 返回的是字段内容开始位置还是记录结束位置？

它返回当前字段起点的行号和字节列号。字段内部如果包含换行，后续内容不会改变这个起点坐标。

ParseError 和 FieldPos 能不能互相替代？

不能。ParseError 描述解析失败范围，FieldPos 描述成功读出的记录中某个字段的起点；一个用于失败分支，一个用于成功记录定位。

为什么我按字符数计算出的列号对不上？

因为标准库返回的是字节列，UTF-8 多字节字符会让字节数和字符数不同。日志中保留字节列，展示层再按需要转换即可。