pd.read_csv() 读出重复列名的常见原因是CSV头部含空格、BOM字符（如\ufeff）或手动构造DataFrame时未去重；Pandas默认静默生成col.1等形式，但完全相同列名会导致KeyError等异常。
为什么 pd.read_csv() 会读出重复列名？
常见原因是原始 CSV 文件头部存在空格、不可见字符（如 \ufeff）、或手动拼接时列名未去重。Pandas 默认不会报错，而是静默生成类似 col、col.1、col.2 的列名——但如果你用 header=None + 手动指定 names=...，或从字典/嵌套列表构造 DataFrame，就可能真正出现完全相同的列名（如两个 'id'），这时 df['id'] 会报 KeyError 或只返回第一个匹配列。
如何检查并定位重复列名？
别依赖 df.columns 直接肉眼扫，要用程序确认：
- 用
df.columns.duplicated().any()快速判断是否存在重复 - 用
df.columns[df.columns.duplicated(keep=False)]列出所有重复的列名（含多次出现的） - 用
df.columns.to_series().duplicated(keep='first')配合布尔索引，可标出哪些位置是“后续重复项”
注意：duplicated(keep='first') 返回 True 表示该列名在之前已出现过，这才是你要清理的目标位置。
怎样安全地重命名重复列（保留语义）？
直接用 df.columns = [...] 赋值容易出错，尤其列数多时。推荐用 df.rename(columns=...) 或构建新列名列表：
- 最稳妥方式：遍历
df.columns，对每个重复名追加序号，例如['id', 'name', 'id.1', 'score', 'id.2'] - 一行写法：
cols = [f"{c}.{i}" if c in df.columns[df.columns.duplicated(keep=False)].tolist() else c for i, c in enumerate(df.columns)]——但注意这仅按首次出现顺序编号，不保证逻辑一致 - 更健壮的做法是先统计频次：
from collections import Counter; counts = Counter(df.columns); seen = {}; new_cols = []，再逐个生成唯一名（如id_0、id_1）
避免用 .add_suffix() 全局加后缀，它不区分是否重复，会污染原本唯一的列名。
遇到 ValueError: cannot insert X, already exists 怎么办？
这是在尝试 df['new_col'] = ... 或 df.insert(...) 时，列名恰好与已有重复列名冲突导致的。根本原因不是“不能插入”，而是 Pandas 在内部做列名校验时发现键已存在。
- 解决路径一：先重命名原重复列，再插入新列
- 解决路径二：改用位置索引插入，如
df.insert(loc=len(df.columns), column='new_col', value=...)，此时 Pandas 不校验列名唯一性（但后续操作仍可能出问题） - 关键提醒：只要列名不唯一，调用
df.groupby(...)、df.pivot()、甚至部分df.to_dict(orient='records')都可能静默丢失数据或抛异常
真正麻烦的不是重命名动作本身，而是下游代码是否隐式依赖列名唯一性——这点很容易被忽略，直到在生产环境某个边缘 case 下突然失败。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
