Python csv.DictReader 表头重复时如何保留原始列

CSV 导出文件里出现两个同名表头时，csv.DictReader 不能自动保留两列。它按字段名建立字典，重复键会让前面的值被后面的值覆盖。要保留原始列，做法是先用 csv.reader 按位置读取，再把重复表头规范化成唯一键；如果还需要字典形式，就把这组唯一键传给后续处理。

为什么 DictReader 会丢掉重复表头

DictReader 的核心工作是把一行数据和 fieldnames 配对后生成字典。字典键必须唯一，所以类似下面的文件：

姓名,姓名,部门
张三,张三（英文）,研发

默认读取后只能通过一个“姓名”键访问到一个值，前一个位置的信息已经无法从结果字典中区分出来。这个行为不是 restkey 的用途：restkey 专门接收“数据列比表头更多”的尾部字段；restval 则用于补齐短行。

先按位置读取，原始列就不会互相覆盖

保留原始列的关键是暂时不要把表头直接当成字典键。用 csv.reader 读取后，表头和每一行都是列表，列表位置天然区分两个同名字段：

import csv
from io import StringIO

csv_text = "姓名,姓名,部门\n张三,张三（英文）,研发\n"

with StringIO(csv_text, newline="") as stream:
    reader = csv.reader(stream)
    headers = next(reader)
    values = next(reader)

    # 按列位置保存，重复表头此时仍是两列独立数据
    original_columns = list(zip(headers, values))
    print(original_columns)

输出中的两个“姓名”分别处在不同位置。生产代码读取真实文件时，仍建议使用 open(path, newline="", encoding="utf-8-sig")，其中 newline="" 让 csv 自己处理换行，utf-8-sig 可顺手跳过部分 Excel 文件开头的 BOM。

给重复字段加后缀，再生成稳定字典

如果后续业务更喜欢字典，可以只在确认保留了位置之后做一次字段名规范化。下面的函数保留第一次出现的原名，第二次开始追加编号；空表头也会获得可追踪的列名。

import csv
from collections import defaultdict
from io import StringIO

def read_csv_with_unique_headers(text: str) -> list[dict[str, str]]:
    # 先读列表，避免 DictReader 过早覆盖重复键
    reader = csv.reader(StringIO(text, newline=""))
    try:
        raw_headers = next(reader)
    except StopIteration:
        return []

    counts = defaultdict(int)
    fieldnames = []
    for index, header in enumerate(raw_headers, start=1):
        base = header.strip() or f"unnamed_{index}"
        counts[base] += 1
        # 第一次保留原名，后续用出现次序形成唯一键
        fieldnames.append(base if counts[base] == 1 else f"{base}__{counts[base]}")

    rows = []
    for line_number, values in enumerate(reader, start=2):
        # 短行补空值，长行集中到额外字段，避免静默截断
        padded = values[:len(fieldnames)] + [""] * max(0, len(fieldnames) - len(values))
        row = dict(zip(fieldnames, padded))
        if len(values) > len(fieldnames):
            row["__extra__"] = values[len(fieldnames):]
        row["__line__"] = line_number
        rows.append(row)
    return rows

result = read_csv_with_unique_headers(csv_text)
print(result[0]["姓名"], result[0]["姓名__2"], result[0]["部门"])

这里的 __line__ 是排查数据时的辅助信息，正式写回业务对象前可以删除。若业务必须保留完全原始的字段名，建议同时保存 raw_headers 和规范化后的 fieldnames，不要让后缀规则成为不可追溯的隐式约定。

restkey、restval 和自定义 fieldnames 怎么选

当表头本身唯一，只是数据行偶尔多一列或少一列时，DictReader 仍然很方便。例如：

import csv
from io import StringIO

text = "name,score\nA,90,unexpected\nB\n"
reader = csv.DictReader(
    StringIO(text, newline=""),
    restkey="__extra__",  # 接收多出的字段
    restval="",            # 给缺失字段补空值
)

for row in reader:
    print(row)

但重复表头的场景应该在进入 DictReader 前完成唯一化。如果你已经从外部规则得到唯一的 fieldnames，也可以把它显式传入，并注意：传入自定义字段名后，文件第一行会作为普通数据行读取，不再自动当作表头跳过。

导入前的检查清单

实际接入外部 CSV 时，先检查表头是否为空、是否含首尾空格、是否重复，以及每行字段数是否与表头一致。不要用 set(headers) 直接判断后就丢弃重复字段；集合只能告诉你“有重复”，不能保留重复项本身。若字段名需要进入数据库或接口，统一后缀规则并在文档中固定下来，避免同一文件在不同批次生成不同键。

相关问题

DictReader 能通过 restkey 保留重复列吗？

不能。restkey 只接收一行里超出字段名数量的尾部值；重复字段名仍会在字典构造时发生键覆盖。

为什么不直接把重复字段变成列表？

如果所有列都用列表，调用方需要同时记住列顺序。更稳妥的做法是保留原始列表，再按明确规则生成唯一键；需要多值语义时也可以额外输出“字段名到值列表”的结构。

短行和空白行要不要报错？

取决于业务契约。报表导入可以用空字符串补齐并记录行号；财务或对账数据通常应记录异常并拒绝写入，不能把缺失值和真实空值混为一谈。

记住一个判断就够了：重复表头是“列身份”问题，不是 restkey 的宽度问题。先用列表保住位置，再生成唯一字段，数据才不会在第一次转成字典时丢失。