Go encoding/csv 遇到带换行的引号字段为什么不能按行拆分

Go 里遇到带换行的 CSV 字段，先记住一句话：物理行不一定等于逻辑记录。只要换行出现在一对完整的双引号内部，它就是字段内容的一部分，不能先用 strings.Split 或逐行 Scanner 切开，再指望后面恢复原来的列结构。对于 RFC 4180 风格输入，应直接交给 encoding/csv.Reader，让它根据引号状态判断一条记录何时结束。

官方入口：https://pkg.go.dev/encoding/csv#Reader。下面只讨论标准 CSV 的跨行字段，不把自定义日志格式硬套进 CSV 解析器。

先区分物理行与 CSV 记录

例如一条客户记录的备注字段里包含人工换行：

1001,华东仓库,"第一行备注
第二行备注",ready
1002,华南仓库,"无需跟进",ready

从文本表面看，这段输入有三条物理行；按 CSV 语义看，第一条记录从 1001 开始，到 ready 结束，备注里的换行仍属于第三个字段。第二条记录才从 1002 开始。如果直接按 \n 拆分，第一条记录会被截成两段，后续的逗号也会被错误地当作下一行的开头。

这里的关键不是“换行能不能出现在字符串里”，而是解析器是否知道当前位于引号字段内部。Go 的 csv.Reader 按 RFC 4180 风格处理引号字段，逗号和换行都可以成为字段内容；字段首尾的双引号不会出现在返回值里。

按行拆分为什么会破坏语义

常见的第一版代码大致如下：

// 这里只演示错误的边界判断，不建议用于标准 CSV。
func splitPhysicalLines(data string) []string {
    // 物理换行可能位于引号字段内部，不能直接当作记录结束。
    return strings.Split(data, "\n")
}

这段代码的问题不是 strings.Split 本身不可靠，而是它没有 CSV 的上下文：它不知道前面是否遇到未闭合的双引号，也不知道两个连续双引号代表字段中的一个引号。bufio.Scanner 逐行读取同样只是得到物理行，除非业务自己实现完整的 CSV 状态机，否则无法安全拼回带引号的跨行字段。

按行拆分后再用 strings.Split(line, ",") 会叠加第二个问题：引号中的逗号也不是列分隔符。也就是说，跨行字段和字段内逗号都要求解析器同时维护引号状态；只修复换行处理仍然不够。

用 csv.Reader.Read 读取完整记录

读取时把原始数据作为一个连续的 io.Reader 交给标准库。代码中的每个错误都在当前边界返回，成功时一次拿到完整的字段切片：

package main

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

// readRecords 让 csv.Reader 判断引号字段和逻辑记录边界。
func readRecords(data string) error {
    reader := csv.NewReader(strings.NewReader(data))
    // 首条记录确定字段数后，后续记录数量不一致会返回 ErrFieldCount。
    reader.FieldsPerRecord = -1

    for recordNo := 1; ; recordNo++ {
        record, err := reader.Read()
        if errors.Is(err, io.EOF) {
            // EOF 只表示所有完整记录已经读完，不是解析错误。
            return nil
        }
        if err != nil {
            return fmt.Errorf("读取第 %d 条记录: %w", recordNo, err)
        }
        fmt.Printf("record=%d fields=%q\n", recordNo, record)
    }
}

func main() {
    // 换行位于第三个引号字段内部，仍应返回一条完整记录。
    data := "1001,华东仓库,\"第一行备注\n第二行备注\",ready\n"
    if err := readRecords(data); err != nil {
        fmt.Println(err)
    }
}

示例把 FieldsPerRecord 设为 -1，是为了专门观察跨行字段的读取结果，不让字段数量校验掩盖当前主题。如果业务协议要求每条记录必须有固定列数，更适合读取表头或第一条记录后保存列数，再让后续记录按固定数量校验。

正常跨行字段返回的字段值会保留字段内部的换行。Go 的 Reader 会把输入中的 \r\n 统一为 \n，这样不同平台的行尾不会改变返回值的换行约定；这不代表它会把引号字段拆成多条记录。

排查引号不闭合与字段数量问题

看到“读取失败”时，不要把所有问题都归结为跨行字段。至少要区分三种情况：闭合引号包住了跨行内容，这是合法的逻辑记录；引号没有闭合，通常会得到 *csv.ParseError 并可继续判断 ErrQuote；记录列数不一致，则对应 ErrFieldCount，它与引号语法是不同层级的问题。

// classifyCSVError 把语法错误和字段数量错误分开记录。
func classifyCSVError(err error) string {
    var parseErr *csv.ParseError
    if errors.As(err, &parseErr) {
        // ParseError 还带有记录起始行、出错行和字节列位置。
        if errors.Is(parseErr.Err, csv.ErrQuote) {
            return "引号未闭合或引号位置不合法"
        }
        if errors.Is(parseErr.Err, csv.ErrFieldCount) {
            return "记录字段数量不一致"
        }
        return "CSV 语法解析错误"
    }
    if errors.Is(err, io.EOF) {
        // EOF 不是错误分类，表示没有更多完整记录。
        return "读取结束"
    }
    return "底层输入读取错误"
}

LazyQuotes 可以让 Reader 对部分不规范引号更宽容，但它不是“把任意按行文本变成 CSV”的开关。若上游明确承诺 RFC 风格 CSV，默认严格解析更容易尽早发现导出端损坏；只有在兼容历史数据且有后续清洗策略时，才应单独评估是否开启宽松选项。

固定列数还是允许变长记录

字段数量策略要和业务协议一致。默认情况下，第一条成功读取的记录会确定字段数量，后续不一致会报 ErrFieldCount。这适合表格型导入：列数不一致往往意味着文件损坏或上游版本变化。

不要为了避开字段数错误而把所有输入都设成变长。这样虽然能继续拿到切片，却可能把列错位推迟到数据库写入或业务计算阶段，排查成本更高。

什么时候才应该按物理行读取

如果输入协议明确规定“一行就是一条消息”，并且字段内部不允许换行，也不使用 CSV 的引号转义，那么逐行读取可以成立；但此时它更像简单分隔文本，不应再把它描述成完整 RFC 风格 CSV。反过来，只要数据来自表格导出、备注字段可能换行，或者字段中可能出现逗号，就应让 encoding/csv 负责记录边界。

我的判断顺序是：先确认上游格式契约，再选择读取器；不要看到换行就先删掉，看到逗号就先切开。对标准 CSV，最小可靠路径就是连续输入、csv.Reader.Read、明确字段数量策略、分别处理 ParseError 与 io.EOF。

CSV 跨行字段的常见问题

引号字段里的换行会被 Go 自动删除吗？

不会。它仍然是返回字段值的一部分；Reader 会规范化输入中的 CRLF 行尾为 LF，但不会把合法跨行字段拆开或当作多条记录。

为什么读取跨行 CSV 后字段数量还是错？

先检查引号是否成对、字段内的双引号是否按两个双引号转义，再判断是否真的存在列数不一致。跨行本身不是 ErrFieldCount 的原因。

能不能先 Scanner 再把多行拼起来？

可以自行实现完整的引号状态机，但这等于重新实现 CSV 解析。只要输入符合标准 CSV，直接给 csv.Reader 更清晰，也能复用它对引号、逗号、错误位置和字段数的处理。