Go csv.Reader.FieldPos 返回的列号为什么按字节而不是字符

在 Go 的 CSV 排错中，csv.Reader.FieldPos 返回的第二个值经常让人困惑：明明前面只有几个中文字符，列号却比“字符数”大。原因是它描述的是 CSV 源记录中的字节列，不是 Unicode 字符列。

FieldPos 的行号和列号从 1 开始；列号按 UTF-8 字节计数，并且只对应最近一次 Read 返回记录里某个字段的起点。需要字符数量时，另行对已经解码的字符串计算 rune 数量。

先分清字段索引和源码列号

Read 返回的 record 是字段值切片，字段索引从 0 开始；FieldPos(field) 接收的也是这个索引。它返回的行、列则从 1 开始，表示该字段在 CSV 输入中的起点。

package main

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

func main() {
    input := "姓名,城市,备注\n张三,北京,已完成\n"
    reader := csv.NewReader(strings.NewReader(input))

    // FieldPos 必须针对最近一次 Read 返回的 record 查询。
    record, err := reader.Read()
    if err != nil && err != io.EOF {
        panic(err)
    }
    fmt.Println(record)

    // 第二个字段索引为 1；返回位置使用 1-based 行列。
    line, column := reader.FieldPos(1)
    fmt.Printf("字段=%q，行=%d，字节列=%d\n", record[1], line, column)
}

这里第一次 Read 读到表头，字段索引 1 对应“城市”。如果在没有成功读取记录，或传入超出 record 范围的索引后调用，不能把它当作普通的安全查询；官方文档明确说明越界索引会触发 panic。

中文字段为什么会让列号变大

Go 字符串通常保存 UTF-8 编码。一个中文字符通常占 3 个字节，但“字符数”和“字节数”不是同一个坐标系。以上面的第二条数据为例，张三 在逗号前占 6 个字节，因此“北京”字段的源码起点要把这 6 个字节和分隔逗号一起算进去。

所以，不能用“前面有几个中文字符”去反推 FieldPos 的列号，也不能把返回列号直接当作 record[field][column-1] 的字符下标。前者忽略了 UTF-8 多字节编码，后者还忽略了分隔符、引号和 CSV 解码对字段内容的影响。

四种位置 API 应该怎么选

这几个 API 都和“位置”有关，但描述的对象不同。排查时先确定自己是在定位字段、解析错误、读取流偏移，还是统计字段文本。

• FieldPos：定位最近一次成功读取记录中某个字段的源行、源列；列是字节。
• ParseError.Column：解析失败处的 1-based 字节列，适合展示语法错误位置。
• InputOffset：当前读取器位置对应的输入流字节偏移，不是当前行的字符列。
• utf8.RuneCountInString：统计已经解码的字段内容，不返回 CSV 源文件位置。

package main

import (
    "encoding/csv"
    "fmt"
    "unicode/utf8"
)

func report(record []string, field int, line, column int) {
    value := record[field]

    // FieldPos 的 column 是源码字节列；runeCount 是字段内容计数。
    fmt.Printf("源位置=%d:%d，字段=%q，字节数=%d，rune数=%d\n",
        line, column, value, len(value), utf8.RuneCountInString(value))
}

对于多行引号字段，行号和列号仍然是源 CSV 的位置，不能把它简化成“返回字符串中的二维下标”。如果需要在编辑器中标记原文件，应保留字节坐标；如果需要限制字段长度或显示字符数，才对字段字符串单独计算 rune。

排错时的选择表

一句话记忆：FieldPos 回答“字段在 CSV 原文的哪个字节位置开始”，而 utf8.RuneCountInString 回答“字段值解码后有多少个 rune”。它们服务于不同层次，不能互换。

相关问题

FieldPos 的字段参数从 0 还是 1 开始？从 0 开始，因为它对应 Read 返回切片的索引；返回的行列坐标才从 1 开始。

为什么不能直接用列号切片字段字符串？列号属于原始 CSV 行，可能包含前面的字段、逗号和引号；字段字符串已经经过 CSV 解码，坐标基准已经变化。

中文列号是否说明 CSV 解析错误？不是。只要把它理解为 UTF-8 字节列，它就是稳定且可用于源文件定位的结果。