Python 读 CSV 时第一列总报 KeyError,列名看着一样却取不到?

表格软件里第一列就叫 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 上对着合成文件跑通的。打开的那两页官方文档,标题里写的是滚动文档自己标的版本,不是这次实跑的版本,也不能当成功能的最低支持版本。