pandas merge 之后行数暴涨、全是 NaN、dtype 变了？9 个对照表

结论先行：merge 出问题，八成不是语法错，而是连接键的重复值、dtype 不一致、以及 how 的默认值这三件事。本文用 9 组「症状 → 原因 → 修法」对照表，把 merge 的坑一次说清。

坑 1：合并后行数暴涨（笛卡尔积）

症状：左表 1000 行，右表 500 行，merge 完变 5000 行。

原因：连接键在右表有重复值，一对多会逐行展开。

df_right["key"].duplicated().sum()

r = df_right.drop_duplicates(subset="key", keep="last")
df.merge(r, on="key", how="left")

df.merge(r, on="key", how="left", validate="many_to_one")

坑 2：合并后全是 NaN

症状：明明键值一样，右表的列全是 NaN。

原因：dtype 不一致——左表是 int64，右表是从 CSV 读进来的 str，'1001' != 1001。

df_left["key"].dtype, df_right["key"].dtype   # int64 vs object
df_right["key"] = df_right["key"].astype(df_left["key"].dtype)

坑 3：列名冲突变成 _x / _y

症状：合并后出现 score_x、score_y，不知道哪个是自己的。

原因：两表有同名非键列，pandas 自动加后缀。

r = df_right.rename(columns={"score": "score_2025"})
df.merge(r, on="key", how="left")

坑 4：how 默认 inner，数据被悄悄丢了

症状：左表 1000 行，merge 完只剩 800 行。

原因：how 的默认值是 'inner'，只保留交集。

建议：显式写 how=，别依赖默认值。

坑 5：on 与索引混用

症状：KeyError: 'key'，或合并结果不对。

原因：键在索引上而不是列里，得用 left_index=True / right_index=True。

df.merge(r, left_on="key", right_index=True, how="left")

坑 6：int 列合并后变成 float

症状：原本是整数的 age 列，合并后变成 18.0。

原因：该行没匹配上，填入了 NaN，而 NaN 是浮点，整列被向上转型成 float64。

df["age"] = df["age"].astype("Int64")

坑 7：多键合并只匹配了一部分

症状：用 on=["a","b"] 合并，行数比预期少。

原因：多键是按组合匹配的，任一列对不上就整行不匹配。

merged = df.merge(r, on=["a", "b"], how="left", indicator=True)
merged["_merge"].value_counts()   # left_only 有多少

indicator=True 会加一列 _merge，直接告诉你每行是 both 还是 left_only。

坑 8：suffixes 没设，后缀撞车

症状：多次合并后列名变成 score_x_x。

修法：每次合并显式给后缀。

df.merge(r, on="key", suffixes=("", "_right"), how="left")

坑 9：大表 merge 慢、内存爆

症状：几百万行合并时卡死或 MemoryError。

原因：merge 前没做三件事——降 dtype、去无用列、去重。

r2 = r[["key", "val"]].copy()
r2["key"] = r2["key"].astype("category")
df.merge(r2, on="key", how="left")

速查小结

记住三句话：merge 前先查键的 dtype 与重复值；how 一定显式写；加上 validate= 和 indicator=True**，让 pandas 替你把错报出来**。