表格软件里第一列就叫 name,脚本里 row['name'] 却报 KeyError。如果只用 print 打印单个列名字符串,U+FEFF 在不少终端里看起来像空的,'\ufeffname' 就容易被看成 name。这时候不急着改列名字符串或换分隔符。把 csv.DictReader 读到的键名用 repr 打出来,隐藏字符才会出现:
import csv
with open('input.csv', encoding='utf-8', newline='') as f:
reader = csv.DictReader(f)
print(repr(reader.fieldnames))
如果结果是 ['\ufeffname', 'note'],键名本身就不是 'name',按 'name' 去取就会 KeyError。若 repr 给出的是 'name '、'Name' 这类可见差别,那是列名本身不一致。若第一条记录被读成一整列,再去查分隔符。只有键名带上 \ufeff,才接着去核对文件开头三个字节是不是 EF BB BF:
with open('input.csv', 'rb') as f:
print(f.read(3).hex(' ').upper())
有这个前缀时会打出 EF BB BF;确认文件按 UTF-8 导出后,就可以按起始 BOM 处理。用 encoding='utf-8' 打开时,这三个字节会被解成字符 U+FEFF,并且粘在第一列表头上。
csv 模块说明 里,DictReader 在没有传入 fieldnames 时,会把文件第一条记录当作键名,并且这条记录不再作为数据返回。第一列表头一旦带上这个字符,后面每一行字典里第一列的键都会对不上。同一页还写了:传入的如果是文件对象,打开时要加 newline='',让这个模块自己来处理换行。官方脚注补充,若不写 newline='',引号里的换行可能解释不对。在使用 \r\n 的平台上写入时,还可能多出一个 \r。下面的跨行字段样本依赖这项设置,读的时候要一起加上。
codecs 文档 对 encodings.utf_8_sig 的说明是:解码时会跳过数据开头那个可选的 UTF-8 BOM。它不会去删正文中间同样的字符。所以只改 open 的编码为 utf-8-sig,并保留 newline='',再交给 DictReader。这里不要自己传入 fieldnames,让去掉起始 BOM 之后的第一条记录继续当键名。rows 是迭代器,要在 with 里面消费完:
import csv
with open('input.csv', encoding='utf-8-sig', newline='') as f:
rows = csv.DictReader(f)
print(repr(rows.fieldnames))
for row in rows:
print(row['name'], row['note'])
不要对整段文本做 replace('\ufeff', ''),也不要用 errors='ignore' 把解码问题吞掉。字段值里如果本来就有 U+FEFF,全局删除会改掉数据。用合成样本对照过:文件开头有 BOM 时,utf-8 读到的 fieldnames 是 ['\ufeffname', 'note'],取 row['name'] 会触发 KeyError。换成 utf-8-sig 之后,带 BOM 和不带 BOM 的两份文件,键名都是 ['name', 'note'],name 为 小林,引号包裹的 note 仍是 '第一行\r\n第二行'。另放一个值是 '前\ufeff后' 的字段,用 utf-8-sig 读回来,中间那个字符还在。
下面这份回归只构造临时文件,不读业务数据,可以在临时目录里直接跑:
import csv
import codecs
import tempfile
from pathlib import Path
text = 'name,note\r\n小林,"第一行\r\n第二行"\r\n'
with tempfile.TemporaryDirectory() as td:
root = Path(td)
for has_bom, name in ((True, 'bom.csv'), (False, 'plain.csv')):
path = root / name
path.write_bytes((codecs.BOM_UTF8 if has_bom else b'') + text.encode('utf-8'))
print(name, '前三个字节', path.read_bytes()[:3].hex(' ').upper())
with path.open(encoding='utf-8', newline='') as f:
reader = csv.DictReader(f)
print('utf-8', repr(reader.fieldnames))
row = next(reader)
if has_bom:
try:
row['name']
except KeyError:
print('带 BOM 时用 utf-8 取 name 会 KeyError')
else:
raise AssertionError('Expected KeyError')
with path.open(encoding='utf-8-sig', newline='') as f:
reader = csv.DictReader(f)
assert reader.fieldnames == ['name', 'note']
row = next(reader)
assert row == {'name': '小林', 'note': '第一行\r\n第二行'}
print('utf-8-sig', name, '通过')
interior = root / 'interior.csv'
interior.write_bytes(
codecs.BOM_UTF8 + 'name,note\r\nA,"前\ufeff后"\r\n'.encode('utf-8')
)
with interior.open(encoding='utf-8-sig', newline='') as f:
row = next(csv.DictReader(f))
assert row['note'] == '前\ufeff后'
print('正文中间的 U+FEFF 保留')
utf-8-sig 也能读没有 BOM 的 UTF-8 文件,所以上面两份样本可以共用同一种打开方式。不带 BOM 的那份,开头三个字节是 6E 61 6D,也就是 name 的前三个字母。utf-8-sig 不是 GBK 或 UTF-16 的自动识别器,这次回归也没有覆盖这两种导出,更没有做编码自动探测。如果文件开头不是 EF BB BF,而键名仍然对不上,要回头核对导出时用的编码,按实际编码另开,不要把 utf-8-sig 当成万能开关,也不要在这里加 errors='ignore'。
如果 open() 根本没写 encoding,那是默认编码的问题,和本题这个文件开头的 BOM 不是同一处,可以看这篇关于 Windows 上未指定 encoding 的讨论。
上面的断言和开头字节检查,都是在本机 Python 3.13.5 上对着合成文件跑通的。打开的那两页官方文档,标题里写的是滚动文档自己标的版本,不是这次实跑的版本,也不能当成功能的最低支持版本。