Python csv.reader 怎样用 line_num 定位跨行记录错误

很多人在用Python处理带跨行换行字段的CSV文件时，碰到解析报错想定位出错行号，自己手动数行怎么都对不上，用csv.reader自带的line_num属性就能很方便的拿到出错记录的准确起始行，不用自己额外维护计数器。

实际遍历csv.reader对象时，你不需要自己逐行统计文件行号，只需要捕获解析异常时直接读取reader实例的line_num属性，返回的数值就是当前这条记录第一行所在的文件行号，哪怕字段内部嵌了再多换行符，结果也不会偏差。

我第一次排查这类 CSV 导入问题时，最容易被误导的是“第几条记录”和“第几行”看起来像同一个数字。只要某个字段里包含带引号的换行，一个逻辑记录就可能跨过多行，csv.reader.line_num 统计的是底层输入已经读过的物理行数，不是已经返回的记录数。要让这个数字有定位价值，关键是用 newline="" 打开文件，并在捕获 csv.Error 时立即读取它。

先把故障现场固定下来

这个问题通常表现为：日志说“第 120 条记录失败”，人工打开文件却找不到对应行；或者导入工具在一条多行地址记录之后才报错，错误行看起来比预期靠后。先不要用普通的 readline() 自己切行，因为 CSV 的引号规则可能让换行符属于字段内容。

Python 官方文档建议读 CSV 文件时传入 newline=""，让 csv 模块自己处理换行。下面这段代码只负责读取和报告，不把“读取成功”误写成业务数据有效。

import csv

def read_csv_rows(path):
    # newline="" 让 csv 模块识别字段中的换行，不让 open 先改写行边界。
    with open(path, "r", encoding="utf-8", newline="") as source:
        reader = csv.reader(source)
        for row in reader:
            # line_num 是物理输入行号，row 是当前逻辑记录的字段列表。
            yield reader.line_num, row

line_num 为什么比记录计数更适合定位

reader.line_num 表示从源迭代器读过的行数。一个普通记录可能让它增加 1，而包含合法引号换行的记录可能让它增加 2 或更多；因此它不能替代 enumerate(reader, start=1) 的记录序号。

我会把两种信息同时写入日志：记录序号回答“业务上第几条”，line_num 回答“原始文件读到哪里”。这样遇到跨行记录时，排查者可以直接回到原始文件附近，而不会把多行字段误当成多条数据。

import csv

def inspect_rows(path):
    # 记录序号与物理行号分开保存，避免跨行字段造成误判。
    with open(path, "r", encoding="utf-8", newline="") as source:
        reader = csv.reader(source)
        for record_no, row in enumerate(reader, start=1):
            physical_line = reader.line_num
            print(f"记录={record_no}, 物理行={physical_line}, 字段数={len(row)}")

异常发生时怎样留下可复查证据

CSV 语法或引号结构异常时，读取器可能抛出 csv.Error。异常处理要放在消费迭代器的地方，因为错误往往发生在下一次 next(reader) 期间。此时读取 reader.line_num，再把文件名和原始异常一起记录，定位信息就不会只剩一句“导入失败”。

import csv
import sys

def import_rows(path):
    # 把 csv.Error 转成包含文件和物理行号的诊断信息，不吞掉原始异常。
    with open(path, "r", encoding="utf-8", newline="") as source:
        reader = csv.reader(source)
        try:
            for record_no, row in enumerate(reader, start=1):
                # 这里继续放字段数量、必填字段等业务校验。
                if len(row) != 4:
                    raise ValueError(f"记录 {record_no} 字段数为 {len(row)}")
                yield row
        except csv.Error as exc:
            message = f"{path} 在物理行 {reader.line_num} 附近解析失败: {exc}"
            raise ValueError(message) from exc

if __name__ == "__main__":
    # 命令行入口只展示诊断结果，真正的业务处理由调用方决定。
    try:
        list(import_rows(sys.argv[1]))
    except (OSError, ValueError) as exc:
        print(exc, file=sys.stderr)

修复后还要补上哪些边界

修正 newline="" 和异常日志，只能解决“在哪里坏了”的问题，不能判断每条记录是否符合业务协议。导入层还应明确四个约束：固定字段数量、必填字段、编码策略，以及是否允许字段内换行。字段数量不符属于业务校验失败，不应伪装成 csv.Error。

另外，line_num 是读取进度，不是错误字符的列号；它也不保证能指出坏字段的精确字符位置。对需要更细诊断的场景，应保留原始文件片段、方言配置和输入批次标识，但不要把整行可能包含的敏感信息直接写进普通日志。

我的结论

遇到跨行 CSV 导入故障时，可以记住一组简单分工：enumerate(reader) 负责逻辑记录序号，reader.line_num 负责原始物理行位置，csv.Error 负责语法解析异常，字段数量和必填字段检查负责业务合法性。把这四层分开，日志中的“第几条”和文件中的“第几行”就不会再互相误导。

相关问题

• CSV 字段里允许换行时，为什么必须使用 newline=""？
• line_num 能不能直接当作坏字段的精确位置？