Pandas合并时列名冲突会直接报错MergeError: Columns overlap，必须显式指定suffixes（pd.merge）、keys（pd.concat）或提前重命名列来解决，而非依赖自动处理。
合并时列名冲突会直接报错 MergeError: Columns overlap
只要两个 DataFrame 有同名列（哪怕只是部分重叠），pd.merge() 或 pd.concat() 默认都会拒绝执行，并抛出 MergeError: Columns overlap。这不是警告，是硬性拦截——Pandas 不会擅自决定保留哪个、改名哪个，必须由你显式声明策略。
常见触发场景：从多个 Excel 表读取客户数据，都含 "id" 和 "name"；或用 groupby().agg() 后多次调用生成了重复列名的中间结果。
- 别指望 Pandas 自动加后缀——它连提示都不给，直接中断
-
suffixes参数只对pd.merge()中的“连接键以外的重名列”生效，对 concat 完全无效 - 用
pd.concat(..., ignore_index=True)不解决列名冲突，只会让行索引重排，列名照样撞车
pd.concat() 中用 keys 或 names 分层索引隔离列
当你要垂直堆叠（即按行拼接）多个结构相似但列名完全一致的表时，最干净的办法是引入多级列索引（MultiIndex），用 keys 把来源表标出来。这样所有列名被自动提升一层，原始列名不再直接并列，自然避开冲突。
df1 = pd.DataFrame({"A": [1], "B": [2]})
df2 = pd.DataFrame({"A": [3], "B": [4]})
result = pd.concat([df1, df2], keys=["table1", "table2"], axis=0)
# 列变成 MultiIndex: (table1, A), (table1, B), (table2, A), (table2, B)
- 如果只想保留原始列名、丢弃来源标识，后续可调用
result.droplevel(0, axis=1)，但这又会引发重叠——所以不推荐无脑 drop -
axis=1水平拼接时，keys会让列变成二级索引，适合对比不同表的同一指标（如 “Q1_sales”、“Q2_sales”） - 注意：
keys传入的是 list，不是 dict；顺序必须和传入 concat 的 DataFrame 列表严格一致
pd.merge() 中用 suffixes 控制非连接键列的重命名
横向合并（how="inner"/"left"）时，若两表都有 "price"、"category" 等非连接键列，suffixes 是唯一标准解法。它只作用于「非 on/columns 参数指定的列」，连接键列（如 on="id"）本身不会加后缀。
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
立即学习“Python免费学习笔记（深入）”；
df_left = pd.DataFrame({"id": [1, 2], "price": [10, 20], "tag": ["a", "b"]})
df_right = pd.DataFrame({"id": [1, 2], "price": [15, 25], "tag": ["x", "y"]})
merged = pd.merge(df_left, df_right, on="id", suffixes=("_left", "_right"))
# 结果列：id, price_left, tag_left, price_right, tag_right
-
suffixes必须是长度为 2 的 tuple，不能是 list 或单字符串 - 如果某列只在左表或右表存在，
suffixes不影响它；只对双方都存在的非键列生效 - 避免用空字符串做后缀（如
("", "_r")），会导致列名歧义，尤其后续做df["price"]时无法确定选哪个
手动重命名列再合并是最可控的方式
当 suffixes 或 keys 不够用——比如要合并 5 个表、每个都有 "score"，且需保留原始语义（如区分 “math_score”、“eng_score”）——就得提前重命名。这是唯一能 100% 掌控列名的方式。
tables = [df_math, df_eng, df_sci]
renamed = []
for i, df in enumerate(tables):
prefix = ["math", "eng", "sci"][i]
renamed.append(df.add_prefix(f"{prefix}_"))
final = pd.concat(renamed, axis=1)
-
add_prefix()比遍历columns改名更安全，不会误伤 index 名称 - 如果某些列不该加前缀（如共用的
"student_id"），先drop再add_prefix，最后用join或concat拼回去 - 别在合并后 rename——很多操作（如
groupby、agg）对列名敏感，中途改名容易引发隐性错误
重叠列名不是 Pandas 的 bug，是它的防御机制。真正麻烦的从来不是怎么加后缀，而是没在读取源头就约定好列命名规范——比如 Excel 表头写成 “score_math_v2”，而不是统一叫 “score”。这一步省掉，后面所有 merge 都得打补丁。
