Go encoding/csv用 InputOffset 定位原始错误的排查方法

我在排查一批导入失败的 CSV 时，最容易误判的是把 InputOffset() 当成“坏字符的精确下标”。它真正提供的是读取器的字节边界：最近一条记录结束的位置，也是下一条记录开始的位置。要定位原始错误，应把它和 *csv.ParseError 的 StartLine、Line、Column 一起看。

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

先把错误拆成行号、列号和字节偏移

encoding/csv 的 Read 在遇到引号不闭合、裸引号等解析问题时会返回 *csv.ParseError。其中 Line 和 Column 是人读的坐标，InputOffset 是字节流坐标。两类坐标不要混用：多字节中文和跨行引号都会让“字符数”和“字节数”产生差异。

因此，offset 更像书签，而不是红笔圈出的坏字符。图中的边界关系是静态说明，不能当作一次真实运行截图。

用一个小工具把原始 CSV 片段打印出来

为了让偏移可以复查，示例先把文件读成字节切片，再交给 bytes.NewReader。这样遇到错误时既能继续使用 csv.Reader 的语义，也能根据报错行号从原始内容取出上下文。这里允许字段数变化，避免把结构性问题误报成唯一的解析失败。

package main

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

func lineAt(data []byte, line int) string {
    // 按换行切片只用于展示原文，不改变 csv.Reader 的解析结果。
    lines := strings.Split(string(data), "\n")
    if line  len(lines) {
        return ""
    }
    return lines[line-1]
}

func main() {
    data, err := os.ReadFile("input.csv")
    if err != nil {
        // 文件读取失败与 CSV 语法失败分开报告，便于判断责任边界。
        panic(err)
    }

    reader := csv.NewReader(bytes.NewReader(data))
    reader.FieldsPerRecord = -1 // 先允许列数变化，专注定位语法错误。

    for recordNo := 1; ; recordNo++ {
        record, err := reader.Read()
        if errors.Is(err, io.EOF) {
            break
        }
        if err != nil {
            var parseErr *csv.ParseError
            if errors.As(err, &parseErr) {
                offset := reader.InputOffset()
                fmt.Printf("record=%d start_line=%d line=%d column=%d offset=%d\n",
                    recordNo, parseErr.StartLine, parseErr.Line, parseErr.Column, offset)
                fmt.Printf("raw-line=%q\n", lineAt(data, parseErr.Line))
                // offset 是行边界锚点，精确坏位置仍以 line/column 为准。
                return
            }
            panic(err)
        }
        fmt.Printf("record=%d fields=%d\n", recordNo, len(record))
    }
}

这段程序的关键是不要只打印错误字符串：ParseError 能告诉你出错行列，InputOffset 则让日志可以关联到原始字节流的记录边界。生产环境可以把 raw-line 换成脱敏后的片段，并把 offset 作为重试或人工复核的定位键。

按错误类型决定修复动作

ErrFieldCount 通常是列数策略问题；ErrBareQuote 和 ErrQuote 更接近输入转义或引号闭合问题。先确认错误类型，再决定修上游导出、放宽读取配置，还是拒绝该记录。不要为了让导入继续而一律打开 LazyQuotes，它会改变容错范围，可能把脏数据当成合法字段。

• 字段数量变化：若业务允许不定列，设置 FieldsPerRecord = -1，并在业务层检查必需字段。
• 裸引号：优先修复生成 CSV 的转义逻辑，保留原始行便于追溯。
• 跨行字段：结合 StartLine 看完整记录起点，不要只看 Line 的一行。

如果要标出最近一次成功读取的位置，可在每次成功 Read 后记录 InputOffset。发生错误时将它与当前 ParseError 并列输出，就能区分“最后一个好记录的边界”和“当前坏记录的报错坐标”。

常见问题

InputOffset 能直接得到坏字符的下标吗？

不能。它表示最近读完行尾与下一行起点，坏字符位置应结合 ParseError.Line 和 Column，再回到原始字节片段确认。

为什么 Column 不是中文字符数？

官方文档定义列为从 1 开始的字节位置。包含多字节 UTF-8 文本时，不能把它直接当作 rune 下标。

Read 和 ReadAll 该选哪个？

需要定位、记录进度或限制单条影响时选逐条 Read；ReadAll 适合数据量小且只关心最终错误的场景，但不利于细粒度诊断。

我的处理习惯是保留三件东西：错误类型、ParseError 坐标、InputOffset 边界。它们分别回答“错在哪里”“人该看哪一列”“原始数据从哪条记录切开”，比单独记录一行模糊日志更容易复盘。