merge时列名不一致须用left_on和right_on指定左右表连接列，二者互斥于on参数，且需确保列存在、类型兼容、无冗余nan，多列匹配需传列表并注意结果列保留问题。
merge时列名不一致，必须用 left_on 和 right_on
当两个 DataFrame 的连接字段名字不同（比如左边叫 "user_id"，右边叫 "uid"），pd.merge() 默认按列名相同匹配会失败。这时候不能靠重命名硬凑，得明确告诉它“左边用哪列、右边用哪列”。
常见错误现象：KeyError: 'xxx' 或合并结果为空 —— 很可能是因为你只传了 on，但两边根本没有同名列。
-
left_on必须是左表中存在的列名（字符串或字符串列表） -
right_on必须是右表中存在的列名（字符串或字符串列表），且长度要和left_on一致 - 如果要多列联合匹配（比如按用户+时间对齐），两个参数都得传列表：
left_on=["user_id", "date"]，right_on=["uid", "event_date"]
left\_on/right\_on 和 on 同时出现会报错
on 和 left_on+right_on 是互斥参数。只要用了 left_on，就不能再写 on=...，否则抛出 ValueError: Can only pass argument "on" OR "left_on" and "right_on"。
容易踩的坑：复制粘贴旧代码时忘了删掉 on；或者在函数封装里默认写了 on=None，调用时没清理干净。
立即学习“Python免费学习笔记（深入）”；
- 检查逻辑分支：如果某些路径走
on，另一些走left_on/right_on，确保不会混用 - 调试时快速验证：打印
df_left.columns和df_right.columns，确认字段确实存在且拼写一致（大小写敏感）
性能影响：left\_on/right\_on 不影响底层算法，但列类型不匹配会拖慢
left_on 和 right_on 本身不增加计算开销，Pandas 内部还是走哈希连接或排序合并。但如果你选的列是 object 类型（比如全是字符串 ID），而本可以转成 category 或 int64，实际速度可能差几倍。
- 提前检查 dtype：
df_left["user_id"].dtype，如果是object且内容其实是数字，先用.astype(int)转 - 避免在
left_on中使用含空值的列做连接 —— NaN 不参与匹配，会导致行丢失，且不报错 - 如果右表
right_on列有重复值，结果会爆炸式膨胀（笛卡尔积），务必用df_right[col].nunique()看下基数
实际例子：订单表和用户表按不同字段关联
假设你有订单表 orders（含 "cust_no"），用户表 users（含 "customer_number"），想查每个订单对应的用户城市：
merged = pd.merge(
orders,
users,
left_on="cust_no",
right_on="customer_number",
how="left"
)
注意这里没删 "customer_number"，所以结果里会多一列冗余字段。如果不需要，得手动 .drop("customer_number", axis=1)。
另一个典型场景：时间字段格式不一致，比如左表是 "2023-01-01"（str），右表是 datetime64。这时不能直接 left_on="date_str" + right_on="date_dt" —— 类型不兼容会静默返回空结果。必须先统一类型，例如：orders["date_str"] = pd.to_datetime(orders["date_str"])。
最常被忽略的一点：left_on 和 right_on 指定的列，在 merge 后默认保留在结果中。很多人以为它像 SQL 的 USING 那样自动去重，其实不会。要不要删、什么时候删、删哪边，得自己拿主意。
