# Python 读 CSV 时第一列总报 KeyError，列名看着一样却取不到？

**URL:** <https://www.shiqidu.com/t/topic/2135>\
**Category:** 开发调优\
**Tags:** 编程, 问与答, Python\
**Created:** [2026 年11 月 18 日 02:12 UTC](https://www.shiqidu.com/t/topic/2135 "2026-11-18T02:12:34Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

作者： ![shiqidu\_editor](https://www.shiqidu.com/user_avatar/www.shiqidu.com/shiqidu_editor/32/528_2.png) [@shiqidu\_editor](https://www.shiqidu.com/u/shiqidu_editor)\
发布日期： [2026 年11 月 18 日 02:12 UTC](https://www.shiqidu.com/t/topic/2135/1 "2026-11-18T02:12:34Z")

</div>

表格软件里第一列就叫 `name`，脚本里 `row['name']` 却报 KeyError。如果只用 `print` 打印单个列名字符串，U+FEFF 在不少终端里看起来像空的，`'\ufeffname'` 就容易被看成 `name`。这时候不急着改列名字符串或换分隔符。把 `csv.DictReader` 读到的键名用 `repr` 打出来，隐藏字符才会出现：

```python
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`：

```python
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 模块说明](https://docs.python.org/3/library/csv.html) 里，`DictReader` 在没有传入 `fieldnames` 时，会把文件第一条记录当作键名，并且这条记录不再作为数据返回。第一列表头一旦带上这个字符，后面每一行字典里第一列的键都会对不上。同一页还写了：传入的如果是文件对象，打开时要加 `newline=''`，让这个模块自己来处理换行。官方脚注补充，若不写 `newline=''`，引号里的换行可能解释不对。在使用 `\r\n` 的平台上写入时，还可能多出一个 `\r`。下面的跨行字段样本依赖这项设置，读的时候要一起加上。

[codecs 文档](https://docs.python.org/3/library/codecs.html) 对 `encodings.utf_8_sig` 的说明是：解码时会跳过数据开头那个可选的 UTF-8 BOM。它不会去删正文中间同样的字符。所以只改 `open` 的编码为 `utf-8-sig`，并保留 `newline=''`，再交给 `DictReader`。这里不要自己传入 `fieldnames`，让去掉起始 BOM 之后的第一条记录继续当键名。`rows` 是迭代器，要在 `with` 里面消费完：

```python
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` 读回来，中间那个字符还在。

下面这份回归只构造临时文件，不读业务数据，可以在临时目录里直接跑：

```python
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 的讨论](https://www.shiqidu.com/t/topic/1870)。

上面的断言和开头字节检查，都是在本机 Python 3.13.5 上对着合成文件跑通的。打开的那两页官方文档，标题里写的是滚动文档自己标的版本，不是这次实跑的版本，也不能当成功能的最低支持版本。
