Python csv 的八个边界陷阱:两行写进去,四条读回来
上周我把一份从数据库导出的表写成 CSV,交给另一个脚本读回来做对账。写入日志显示两行,读数脚本打印出四条记录,其中两条是空列表。对账脚本把空行当成了「缺字段」,于是整批数据被判成不完整——但文件里其实一个字节都没错,错的是我从没真正读过 open() 的 newline 参数到底管什么。
这篇把我这轮踩到的八个边界一次写完。全部在 Windows 11 + CPython 3.13.14 + 标准库 csv(模块版本 1.0)上实测,每一条都附磁盘字节或回读结果,代码可以直接复制。它属于「边界由谁决定」这一层:一个字段从哪里开始、一条记录在哪里结束,不是数据决定的,是 dialect 加 open() 的换行模式共同决定的。同一条线上的前几篇分别讲过导入解析(Python 模块导入语义)、数值舍入(round 与 Decimal 的八个分歧)和文本加粗的贴合规则(CommonMark 与中文标点),本篇补的是最外层那道边界。
TL;DR:csv.writer 自己就会写 \r\n,如果再让文本模式翻译一次,磁盘上会变成 \r\r\n,而 reader 只认 \r 和 \n,于是每行后面多出一条空记录(写 2 行变 4 条)。读写都要显式 newline='';引号里的 \r\n 在默认读取模式下会被折成 \n;QUOTE_NONNUMERIC 会把未加引号的字段一律转成 float;None 与空串往返一次就分不开,要区分只能用 3.12 起的 QUOTE_NOTNULL 或 QUOTE_STRINGS。
一、两行写进去,四条读回来
先复现。第一步用一个最普通的写法写文件,第二步按最普通的方式读回来:
import csv
with open("demo.csv", "w", encoding="utf-8") as f:
w = csv.writer(f)
w.writerow(["name", "qty"])
w.writerow(["widget", 3])
磁盘上的字节是这样的(用 open(path, "rb").read() 看):
b'name,qty\r\r\nwidget,3\r\r\n'
注意 \r\r\n——两个回车加一个换行。csv.writer 的 lineterminator 默认就是 \r\n,而文本模式的 open() 在 Windows 上又会把 \n 翻译成 \r\n,于是多出一个 \r。读回来时 csv.reader 把 \r 和 \n 都当行尾,所以 \r\r\n 被切成「一行结束 + 一条空记录」:
回读 rows: [['name', 'qty'], [], ['widget', '3'], []]
记录数: 4(写入 2 行)
字段本身是干净的,qty 依旧是 'qty',没有残留 \r。这就是它难查的原因:按字段值对账永远对得上,只有按记录数、或者直接遍历 for row in reader 时空行才会跳出来。同一份数据改成 newline='' 写入,磁盘是 b'name,qty\r\nwidget,3\r\n',回读 2 条记录,一条不多。
Python 官方文档在 csv.reader 和 csv.writer 两处都写了「If *csvfile* is a file object, it should be opened with newline=''」,但真正的解释在脚注里,原文是:「If newline='' is not specified, newlines embedded inside quoted fields will not be interpreted correctly, and on platforms that use \r\n line endings on write an extra \r will be added.」——「多出一个 \r」这件事文档写得很清楚,只是它藏在脚注里,正文只有一句话。
二、newline 参数管的是两次翻译里的第二次
要理解上面那行 \r\r\n,得先拆开「换行」在 Python 里走的两道工序。
第一道在 csv.writer 里:它按 lineterminator 拼出 \r\n,然后把字符串交给文件对象。第二道在 io.TextIOWrapper 里:文本模式默认 newline=None,写出去的 \n 会被翻译成系统默认换行(Windows 是 \r\n)。两道都开,就叠成 \r\r\n。newline='' 的意思是「第二道不要做转换」,于是只剩 csv 自己那道,字节干净。
读取侧同理,只是方向反过来。newline=None 时,TextIOWrapper 会在读取阶段就把 \r\n 和 \r 统一成 \n,然后才交给 csv.reader。这意味着字段内部的内容已经被改过一次,csv 拿到的不是磁盘上的原文。下一节就是这个后果。
顺手记一条判据:一个 CSV 文件到底该不该加 newline='',看的是「写完之后的字节」。同一段代码在 Linux 上跑出来的 \r\n,搬到 Windows 上会变成 \r\r\n——所以「在我机器上是好的」这句话,在 CSV 这条链路上几乎没有信息量。
三、引号里的换行被折掉了:字段值变了,行数没变
构造一个字段内含换行的记录,分别用 newline='' 和默认方式读:
import csv
with open("note.csv", "w", newline="", encoding="utf-8") as f:
w = csv.writer(f)
w.writerow(["id", "note"])
w.writerow([1, "line1\r\nline2"])
磁盘:b'id,note\r\n1,"line1\r\nline2"\r\n'。两种读法的结果不一样:
newline='' -> [['id', 'note'], ['1', 'line1\r\nline2']]
newline=None -> [['id', 'note'], ['1', 'line1\nline2']]
字段从 13 个字符变成 12 个,\r 消失了。没有异常、没有警告,len(row) 也没变。对纯文本展示毫无影响,但如果你把字段值做哈希、做签名校验,或者这段内容是带格式的富文本,差异就在那儿躺着。我在一个「按内容哈希去重」的脚本上撞过这个:同一份文件在两台机器上算出的哈希不同,因为一台把文件当成 UTF-8 文本直接读,另一台走的是 newline=''。
反过来,如果你就是要统一成 \n(比如入库前规范化),那默认模式反而省事——但得知道这是你在主动改写数据,而不是「读到了原文」。
四、reader 只认回车和换行:lineterminator 写了也不生效
有一种误解是「writer 和 reader 用同一个 lineterminator,就能自定义行分隔符」。实测不行:
import csv
with open("pipe.csv", "w", newline="", encoding="utf-8") as f:
w = csv.writer(f, lineterminator="|")
w.writerow(["a", "b"])
w.writerow(["c", "d"])
磁盘是 b'a,b|c,d|'(两行用 | 隔开)。但无论 reader 传不传 lineterminator,结果都一样:
reader(默认) -> [['a', 'b|c', 'd|']]
reader(lineterminator='|') -> [['a', 'b|c', 'd|']]
整个文件塌成一条记录,| 被当成了字段内容。官方文档 Dialect.lineterminator 那节有一条 note,原文:「The reader is hard-coded to recognise either '\r' or '\n' as end-of-line, and ignores *lineterminator*. This behavior may change in the future.」——reader 侧完全无视这个参数。
所以「自定义行分隔符」在 csv 里只做得到一半:写得出去,读不回来。真需要别的记录分隔符,只能自己按行切再交给 reader(csv.reader 接受任何字符串可迭代对象),或者换一种格式。
五、QUOTE_NONNUMERIC 的两副面孔
QUOTE_NONNUMERIC 是一个读写语义不对称的开关。写的时候它的意思是「所有非数字字段都加引号」,读的时候它的意思是「所有没加引号的字段都转成 float」。后者比前者危险得多。
先看读一个普通文件会怎样。下面的表头没有引号:
with open("plain.csv", "w", newline="", encoding="utf-8") as f:
f.write('code,name\n0012,"Widget"\n,empty\n')
按 QUOTE_NONNUMERIC 去读,第一行就炸:
ValueError: could not convert string to float: 'code'
因为 code 没有引号,解析器试图把它转成 float。这条报错本身是好事——它至少拦住了你。更值得记的是写读配对之后的行为:
import csv
with open("pair.csv", "w", newline="", encoding="utf-8") as f:
w = csv.writer(f, quoting=csv.QUOTE_NONNUMERIC)
w.writerow(["code", "qty", "price"])
w.writerow(["0012", 12, 1.5])
磁盘:b'"code","qty","price"\r\n"0012",12,1.5\r\n'。读回来是 [['code', 'qty', 'price'], ['0012', 12.0, 1.5]],类型分别是 str / float / float。前导零保住了(因为 '0012' 是字符串,被加了引号),但整数 12 变成了 12.0。凡是「字符串形态的数字」和「真数字」混在一列里,读回来就只能靠类型检查去猜。
还有一个官方明写、但很容易踩的坑:bool 的字符串表示转不成 float。我写 True(作为 bool,它没被加引号),磁盘上是 True,再用 QUOTE_NONNUMERIC 读回来:
ValueError: could not convert string to float: 'True'
文档在 QUOTE_NONNUMERIC 下面专门加了一段 Note:「Some numeric types, such as bool, Fraction, or IntEnum, have a string representation that cannot be converted to float. They cannot be read in the QUOTE_NONNUMERIC and QUOTE_STRINGS modes.」——写得出、读不回。
六、转义字符要写读配对,否则反斜杠会留在数据里
doublequote=False 的意思是「字段里的引号用 escapechar 前缀转义,而不是重复一遍」。如果只关掉双写、又没给转义字符,writer 会直接拒绝:
import csv, io
buf = io.StringIO()
csv.writer(buf, doublequote=False).writerow(['he said "hi"'])
_csv.Error: need to escape, but no escapechar set
补上 escapechar="\\" 之后写出的磁盘内容是 b'he said \\"hi\\","a,b"\r\n'。这时候如果读侧不配对,反斜杠就留在数据里:
reader({}) -> [['he said \\"hi\\"', 'a,b']]
reader({'escapechar': '\\'}) -> [['he said "hi"', 'a,b']]
文档里 escapechar 的属性说明写了两侧语义:「On reading, the *escapechar* removes any special meaning from the following character. It defaults to None, which disables escaping.」——默认关掉。所以「写的时候用了转义、读的时候没开」,得到的是带反斜杠的字符串,而且它长得像合法数据,肉眼很难判断。
同一个报错还有一种来源:QUOTE_NONE 写含分隔符的字段。csv.writer(buf, quoting=csv.QUOTE_NONE).writerow(["a,b"]) 同样抛 need to escape, but no escapechar set,因为 QUOTE_NONE 下逗号必须靠转义字符躲开,而默认没有转义字符。
七、BOM 与字段上限:一个换掉键名,一个直接中断
Excel 保存的「CSV UTF-8」会带 BOM(EF BB BF)。用 encoding='utf-8' 读,BOM 会变成第一个字段名的一部分:
fieldnames(utf-8): ['\ufeffid', 'name']
row: {'\ufeffid': '1', 'name': 'alpha'}
row['id'] -> KeyError: 'id'
row.get('id') -> None
KeyError 至少会响,row.get('id') 返回 None 就彻底静默了——一行数据看起来「这一列是空的」。改法只有一个:读的时候用 encoding='utf-8-sig'(写的时候也用 utf-8-sig 才叫对等),fieldnames 就回到 ['id', 'name']。判据很好写:把 fieldnames 打印出来,看到带 \ufeff 前缀的键,就是这一条。
字段上限是另一类:它不静默,但报错文案里的数字容易让人以为是代码写错了。默认值 131072:
python -c "import csv; print(csv.field_size_limit())"
131072
用一个 20 万字符的字段去读(比上限多 152.6%):
_csv.Error: field larger than field limit (131072)
这个常量不在文档正文里,只能实测或读源码——CPython 3.13 的 Modules/_csv.c 里是 module_state->field_limit = 128 * 1024;。要放开就用 csv.field_size_limit(10 * 1024 * 1024),但先想清楚:单个字段上 10 MB,通常说明这一列不该是 CSV 字段(JSON 或附件路径更合适)。
八、None 与空串:往返一次就分不出来了
数据库里 NULL 和空字符串是两个值,写进 CSV 再读回来就只剩一个。这是官方设计,文档原话:「the value None is written as the empty string. While this isn't a reversible transformation, it makes it easier to dump SQL NULL data values to CSV files without preprocessing the data returned from a cursor.fetch* call.」
实测往返:
写: ',,0,0\r\n'
读: [['', '', '0', '0']]
None == '' ? True
None、''、以及「这一列本来就没有」在读完的列表里完全等价。DictReader 还叠了一层:缺列时用 restval(默认 None)补,所以「缺列」和「值就是 NULL」也变成同一个 None。
3.12 起有两个新常量专治这件事。QUOTE_NOTNULL 写的时候给非 None 的字段加引号、None 写空且不加引号;读的时候把「未加引号的空字段」解释成 None。于是 None 和 '' 在磁盘上终于长得不一样:
磁盘: b'"a","b","c"\r\n,"","x"\r\n'
QUOTE_NOTNULL -> [['a', 'b', 'c'], [None, '', 'x']]
注意读侧要用同一个常量才认得出来:用默认的 QUOTE_MINIMAL 读同一份文件,得到的是 ['', '', 'x'],None 又变成了空串。这一对常量是双侧开关,只改一侧等于没改。如果你还在 3.11 或更早,只能自己在字段值外面包一层编码(比如用 \N 表示 NULL),没有别的办法。
九、排错实录:六个能复现的报错和改法
下面六个报错全部在本机复现过,文案照抄。
报错一:_csv.Error: iterator should return strings, not bytes (the file should be opened in text mode)
现象:读文件第一行就中断。原因:以 'rb' 打开文件喂给 csv.reader,它拿到的每一行是 bytes。改法:改用文本模式并带上 newline='';确实要自己处理编码时,用 io.TextIOWrapper(open(p,'rb'), encoding='utf-8-sig', newline='')。
报错二:_csv.Error: field larger than field limit (131072)
现象:读到某一行突然中断,前面几万行都正常。原因:单个字段超过 131072 字符。改法:先确认是不是某列塞了长文本;确实需要就 csv.field_size_limit(10 * 1024 * 1024),别直接调到 sys.maxsize。
报错三:_csv.Error: need to escape, but no escapechar set
现象:写文件时报错,且只在某些行出现。原因:doublequote=False 或 quoting=QUOTE_NONE 下遇到需要转义的字符(引号、分隔符、换行),而 escapechar 是 None。改法:要么保留默认的 doublequote=True(引号双写),要么显式给 escapechar 并在读侧也传同一个值。
报错四:ValueError: could not convert string to float: 'code'
现象:读第一行表头就炸。原因:用了 quoting=QUOTE_NONNUMERIC,而未加引号的表头被当成数字。改法:表头单独读(先 next(reader) 拿表头再换 reader),或者干脆别用 QUOTE_NONNUMERIC,读成字符串后自己做类型转换。
报错五:KeyError: 'id'(读带 BOM 的文件)
现象:DictReader 的键名看起来是 id,取值却报 KeyError。原因:键名实际是 '\ufeffid'。改法:encoding='utf-8-sig';诊断时先 print(reader.fieldnames) 看有没有 \ufeff。
报错六:_csv.Error: unexpected end of data
现象:只有开了 strict=True 才出现,默认模式下不报错。原因:引号没有闭合。默认 strict=False,解析器会把剩余内容全部吞进当前字段(包括后面的换行),于是「少了几行」而不是「报错」。改法:对来源不可信的文件一律 strict=True,让它在第一处坏数据上停下来;同时把 reader.line_num 打进日志,它是物理行号而不是记录号(实测第 2 条记录的 line_num 是 4,因为上一条记录跨了 3 行)。
十、我实际会跑的五条检查
写完这篇文章,我把这轮踩到的坑压成了五条,每次接手一个新的 CSV 都跑一遍:
- 写文件的地方搜一遍
open(,确认每个csv.writer都带newline=''; - 读完之后断言记录数,而不是只断言第一行字段——
\r\r\n只会改变记录数; - 打印
reader.fieldnames,看到\ufeff就换utf-8-sig; - 需要区分
NULL与空串时,读写两侧都上QUOTE_NOTNULL(3.12+),否则显式约定一个哨兵值; - 对外部来源的文件加
strict=True,并把line_num写进异常日志。
还有一个不属于「错误」但每次都会浪费我时间的:csv.Sniffer。它在单列样本上直接失败(Error: Could not determine delimiter),在 hello|world 这种文本上会把分隔符猜成字母 o——因为文档里 Sniffer.preferred 的初始值是 [',', '\t', ';', ' ', ':'],管道符不在其中,猜出来的东西就纯靠模式匹配的运气。凡是「先嗅探再解析」的代码,都要留一条人工指定 dialect 的退路。
另外,中文环境下还有一种「整行变成一个字段」:文件里用的是全角逗号。默认 delimiter=',' 不会切,row 只有一个元素,也不报错。必须显式传 delimiter=','。
十一、本文的边界:没测什么
- 只测了 CPython 3.13.14(Windows 11)。3.12 之前没有
QUOTE_NOTNULL/QUOTE_STRINGS,第八节的解法在旧版本上不成立;3.10 之前escapechar自身的转义行为也不同(文档写明 3.10 与 3.11 两处 Changed)。 - 没测大文件吞吐:本篇所有结论都基于小样本,
csv的解析速度与文件大小无关,但与字段长度、引号密度有关,因此没有给出任何耗时数字。 - 没测 Excel 的
sep=,首行约定,也没测\r单独作行尾的旧 Mac 文件。 - 只做了 pandas 2.3.1 的一个对照(
read_csv(dtype=str)能保住'0012'的前导零),没有展开 pandas 的 C 引擎与csv模块在引号处理上的差异——那是另一个题目。
本文不含任何联盟推广链接;所有版本号、字节内容和报错文案都来自本机实测与 CPython 官方文档/源码,没有引用二手教程的结论。
如果你正在处理的是「本机一个 GB 级 CSV 想秒级查完」,那不在这篇范围内,可以看 DuckDB 直接读 CSV 的实测;如果你撞的是「看起来一样的字符串不相等」,那属于 Unicode 规范化 那一层。
常见问题
Q:newline='' 到底是给谁的参数?
给 open() 返回的 TextIOWrapper,不是给 csv。它关掉的是文本层的换行转换,让 csv 自己拼的 \r\n 原样落盘。所以只加在 csv 那一侧没有意义——csv.writer 根本没有这个参数。
Q:为什么不用 pandas 一把梭,省掉这些坑?
用 pandas 只是把这些边界挪进了 read_csv 的参数里(dtype、keep_default_na、na_values、encoding),坑还在,只是换了名字。而且 read_csv 默认会把 NA、N/A、null 这些字符串当成缺失值,跟你自己的哨兵值可能打架。标准库的好处是每一层都能看到。
Q:3.11 及以前真的没法区分 None 和空串吗?
没法用 csv 自带的能力区分。None 一定写成空,读回来一定是 '',restval 也默认 None。要么升级到 3.12+ 用 QUOTE_NOTNULL,要么自己在字段值层做编码(例如用 \N 表示 NULL、用两个反斜杠加 N 表示字面量),并且读写两侧遵守同一套约定。
Q:这条线和上一篇「模块导入」有什么关系?
同一类问题的两个方向:上一篇讲「你 import 进来的到底是哪个文件」,本篇讲「你读回来的到底是一条还是两条记录」。共同点都是——代码没有报错,程序拿到的对象和你想的不是同一个。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。