李祯煜做数据分析，几乎逃不开一个操作：把好几张表合成一张表。Pandas 里，这个动作最常用的实现就是 merge()。我第一次用 merge 是在处理订单数据的时候，订单表、用户表、商品表各管一头，分析个销售额还得手动拉 Excel 匹配半天，后来学会了 merge，才真正体会到什么叫“一行代码解决一小时手工活”。这篇文章不是官方文档的复读，而是我自己从多次合并实践中提炼出来的参数用法、踩坑记录和排查经验，适合刚接触 Pandas、准备做表合并的新手，也适合已经会用 merge 但总被莫名报错折磨的朋友。
很多人一上来就翻 Pandas 中文手册，看到一堆参数发怵。我的建议是：merge 这一节先看官方文档，参数解释更准确；网上流传的中文手册当工具书用，遇到生词再翻。你不需要背完所有参数，真正高频的其实就那么几个：how、on、left_on/right_on、suffixes、indicator、validate。把这几个搞透，90% 的合并需求都能搞定。
1. merge 到底是什么：用“对齐”的思路理解表合并
1.1 为什么需要合并多个数据表
真实业务里的数据几乎不会存在一张表里。电商系统里，订单表只存 user_id 和 product_id，用户姓名在用户表，商品价格在商品表。要分析“哪个城市的用户最喜欢买贵的手机”，就得同时用到三张表的信息。这种把多张小表合成一张宽表的过程，就是数据表合并。
我见过不少初学者喜欢用 Excel 的 VLOOKUP 硬凑，列一多就乱。在 Pandas 里，merge() 做的事和 VLOOKUP 类似，但强大得多：它可以按多列匹配、支持四种连接方式、还能告诉你每行数据到底匹配到了没有。与其手动拉表，不如把规则写成代码，以后数据更新了，跑一遍脚本就能出结果。
另外提一句，如果你在 PyCharm 里装 pandas 一直装不上，大概率是解释器环境没选对。先在左下角解释器设置里切换到当前项目用的虚拟环境，再用 pip install pandas 安装，基本一次就通。
1.2 merge、concat、join 的分工别搞混
很多新手把 merge() 和 concat() 混在一起。其实两者解决的是完全不同的问题：
concat()是“堆叠”，纵向把两张表首尾相接，或者横向把两列拼在一起，它不关心两个表之间有什么对应关系。merge()是“连接”，横向把两张表并排拼到一起，但能不能拼上，取决于你指定的键（key）是否相等。DataFrame.join()是merge()的一种简写，默认按索引连接，本质上还是 merge。
| 操作 | 方向 | 连接依据 | 典型场景 |
|---|---|---|---|
concat(axis=0) |
纵向 | 无 | 把 1 月、2 月、3 月的记录拼成一个完整表 |
concat(axis=1) |
横向 | 仅位置 | 两张行数相同的表并排放 |
merge() |
横向 | 指定列的值 | 订单表关联用户表 |
join() |
横向 | 索引 | 按行号对齐的补充信息 |
一句话记忆：要“凑行数”用 concat，要“匹配字段”用 merge。
1.3 这篇文章能帮你解决什么
我写这篇的定位很明确：第一，帮你建立对 merge 的直觉，知道四种连接方式各自会产生什么结果；第二，把高频参数的适用场景讲透，让你在真实业务里不用东查西查；第三，把最常见的坑提前踩好，比如合并后行数翻倍、键类型不一致导致全是 NaN、以及别把 Pandas 的 merge 和 Git 的 merge 搞混。
文章里所有代码都是完整可跑的，建议你打开 Jupyter 或者写个 .py 文件边看边试。数据量小的时候，运行结果一目了然，比干看文档强十倍。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. merge 核心参数逐个拆解：看懂这六个参数就够了
2.1 how 参数：四种连接方式到底选哪个
how 是 merge 里最重要也最容易被忽略的参数。它决定的是“哪些行能留下来”。很多教程会用集合的相交、并集来比喻，我换个更贴近 Excel 的说法：
how='inner'：和 VLOOKUP 一样，只在两表都匹配得上的时候才返回。匹配不上的行直接消失。how='left'：以左表为准，左表每一行都保留，右表匹配不上的部分填 NaN。相当于“左表是主表，其他表是补充信息”。how='right'：和 left 相反，以右表为准。how='outer'：两边都保留，匹配不上的各填各的 NaN。相当于“求并集”。
看个实际例子：
python复制import pandas as pd
users = pd.DataFrame({
'user_id': [1, 2, 3, 4],
'name': ['小明', '小红', '小刚', '小美']
})
orders = pd.DataFrame({
'order_id': [101, 102, 103],
'user_id': [1, 2, 99]
})
print(pd.merge(orders, users, on='user_id', how='left'))
输出：
text复制 order_id user_id name
0 101 1 小明
1 102 2 小红
2 103 99 NaN
第 3 行订单对应的 user_id=99 在用户表里不存在，因为是 left join，所以订单行保留，但 name 为 NaN。如果你用的是 inner，这行订单直接没了。
注意：日常业务里 90% 的情况用
how='left'就够了。“我想保留左表全部数据”这个需求出现的频率远超其他几种。
2.2 on、left_on/right_on：找准连接键
on 用来指定按哪一列连接。条件是：这一列在左右两个表里都存在，且列名完全一样。
python复制pd.merge(orders, users, on='user_id', how='left')
但你经常会遇到“同一个实体在不同表里叫不同的名字”的情况。比如用户表里的 ID 叫 id，订单表里的叫 user_id。这时候就要用 left_on 和 right_on 分别指定：
python复制users2 = users.rename(columns={'user_id': 'id'})
pd.merge(orders, users2, left_on='user_id', right_on='id', how='left')
还有一个细节很多人没意识到：如果不传 on，pandas 会自动把左右两表的公共列当作连接键。听起来很方便，但有坑——如果两个表里恰好有两个相同名字但含义不同的列，它会把两列都当成键来匹配，结果常常和你预期不符。我建议永远显式传入 on 或 left_on/right_on，宁可多打几个字，也别靠猜。
2.3 重复列名不用怕：suffixes 参数
合并两张表时，如果两边都有同名但含义不同的列，pandas 会自动给它们加上后缀。默认是 _x 和 _y，对应左表和右表。
举个例子，订单表里有个 price 表示成交价，商品表里也有个 price 表示标价。不处理直接合并，结果里会出现 price_x 和 price_y。我强烈建议你主动用 suffixes 参数起名，让结果可读性更高：
python复制pd.merge(
orders,
products,
on='product_id',
how='left',
suffixes=('_成交价', '_标价')
)
这样结果就是 价格_成交价 和 价格_标价，一眼看出谁是谁。
2.4 indicator=True：快速定位匹配状态
这是一个被严重低估的参数。合并的时候加上 indicator=True，结果里会多出一列 _merge，取值为 left_only、right_only、both，分别表示该行只出现在左表、只出现在右表、两边都有。
python复制res = pd.merge(orders, users, on='user_id', how='outer', indicator=True)
print(res['_merge'].value_counts())
这一步在数据质量排查时极其好用。比如你做了个 left join，发现结果行数跟左表不一致，怀疑有重复键，用 value_counts() 看一眼 _merge 的分布，立刻就能知道哪些订单没匹配上用户。
2.5 validate：让 merge 按你的预期跑
validate 参数的作用是“校验合并关系”，如果合并结果不符合你的预期，直接报错。它接收四个值：one_to_one、one_to_many、many_to_one、many_to_many。
python复制# 如果订单表同一个 user_id 有多条，而 users 表 user_id 唯一，
# 这个操作其实是一对多合并；
# 但如果你误写成 one_to_one，就会报 MergeError
pd.merge(orders, users, on='user_id', how='left', validate='one_to_one')
报错信息类似于：
text复制MergeError: Merge keys are not unique in right dataset; not a one-to-one merge
这个参数最大的价值是作为“安全断言”。在写自动化数据处理脚本时，数据源变了会导致合并结果悄悄变多。加上 validate，不符合预期就会立刻暴露，而不是等下游数据算完才发现错了。
2.6 sort 和 copy 等边缘参数
sort=True 会在合并后按连接键排序，默认是 False。数据量大的时候排序是很浪费时间的，除非你后面正好需要有序结果，否则保持默认就好。copy 参数在现代版本里基本不需要改，保持默认。
还有个细节：merge 之后行顺序是乱的，这和 Excel 里 VLOOKUP 保持左表顺序不一样。如果你希望结果保持左表原始顺序，可以在合并前给左表加一列序号，合并后再按序号排序回去。
3. 多键合并与索引合并：真实业务里的高级玩法
3.1 多列联合键：一张表搞不定的唯一标识
有时候单靠一列没法唯一标识一行。比如销售明细表里有 year、month、product_id，只有这三列组合起来才能唯一确定一条记录。另一张月度目标表里也有这三列。这时候把多个列放进 on 的列表里即可：
python复制pd.merge(
detail,
target,
on=['year', 'month', 'product_id'],
how='left'
)
多键合并的本质是：左表的 year、month、product_id 三列的值，必须和右表的对应三列同时相等，才算匹配上。你可以把它理解成一个“复合条件匹配”，只要有一列不相等，就匹配不到。
业务里最常见的多键场景是日期加维度。例如用“月份 + 门店编号”去关联门店月度 KPI；用“城市 + 渠道”去关联城市渠道投放金额。遇到这类需求，别急着用单列 merge 后再校验，直接上多键。
3.2 索引合并：当你的“键”是行号时
索引合并适合两种场景：一是某张表的行索引本身就代表实体 ID；二是你不想把索引列还原成普通列，想直接用索引当键。
python复制# 左表用 user_id 列，右表用索引
pd.merge(orders, users, left_on='user_id', right_index=True, how='left')
这里要求右表的索引值恰好等于 orders 里的 user_id 值。如果 users 的索引只是 0、1、2、3 这种默认行号，而 user_id 是另一列，那这种写法会全错。索引连接要格外小心，最好先确认 right.index 和 left[on] 的取值确实是对应的。
3.3 理解笛卡尔积：为什么合并后行数会暴涨
这是 merge 最经典的一个坑。当连接键在任一表里有重复时，合并出来的行数就不是简单相加，而是匹配次数相乘。
python复制left = pd.DataFrame({'key': ['a', 'a', 'b'], 'value': [1, 2, 3]})
right = pd.DataFrame({'key': ['a', 'a', 'a', 'b'], 'value2': [10, 20, 30, 40]})
res = pd.merge(left, right, on='key')
print(res.shape) # (7, 3)
key='a' 在左表有 2 行，在右表有 3 行，匹配后就产生 2×3=6 行；key='b' 两边各有 1 行，产生 1 行。合起来 7 行。这就是笛卡尔积。
业务场景里，如果订单表一个 user_id 有多条订单，用户表一个 user_id 对应一条用户信息，那么是一对多合并，行数不变。但如果你把两个都是多行的表按同一个键合并，行数就会迅速膨胀。合并前先数一下键的重复情况，能帮你省掉一整天的排查时间。
| 连接键情况 | 合并结果行数 |
|---|---|
| 左表唯一、右表唯一 | 两表行数取交集 |
| 左表唯一、右表重复 | 行数 = 左表匹配行的数量（一对多） |
| 左表重复、右表唯一 | 行数 = 右表匹配行的数量（多对一） |
| 两边都重复 | 行数按重复次数相乘，可能暴涨 |
4. 完整实操：把订单、用户、商品三张表合并成订单宽表
4.1 准备三张原始数据表
我模拟一个电商场景：订单表 orders、用户表 users、商品表 products。实际工作中这三张表通常是从数据库导出或读取 CSV、Excel 得到的。用 Pandas 读文件的方式如下：
python复制# 从 CSV 读取
orders = pd.read_csv('orders.csv')
# 从 Excel 读取指定工作表
users = pd.read_excel('users.xlsx', sheet_name='用户表')
products = pd.read_excel('products.xlsx', sheet_name='商品表')
为了演示方便，我直接在代码里构造数据：
python复制import pandas as pd
users = pd.DataFrame({
'user_id': [1, 2, 3, 4],
'name': ['小明', '小红', '小刚', '小美'],
'city': ['北京', '上海', '广州', '深圳']
})
products = pd.DataFrame({
'product_id': [101, 102, 103],
'product_name': ['手机', '耳机', '充电宝'],
'price': [5000, 200, 89]
})
orders = pd.DataFrame({
'order_id': [1001, 1002, 1003, 1004, 1005],
'user_id': [1, 2, 2, 4, 1],
'product_id': [101, 102, 101, 103, 102],
'quantity': [1, 2, 1, 1, 3]
})
注意一个细节：orders 里 user_id 是有重复的，同一个用户下了多单，所以订单表对用户表是“多对一”的关系。后面合并时这个细节很关键。
4.2 第一步：订单表关联用户表
目标是把用户姓名、城市补到订单明细里。因为订单表是主表，用 how='left' 保留全部订单：
python复制step1 = pd.merge(orders, users, on='user_id', how='left')
print(step1)
输出：
text复制 order_id user_id product_id quantity name city
0 1001 1 101 1 小明 北京
1 1002 2 102 2 小红 上海
2 1003 2 101 1 小红 上海
3 1004 4 103 1 小美 深圳
4 1005 1 102 3 小明 北京
step1 共 5 行，和 orders 一致，说明所有订单都匹配到了用户。这里不用 validate 也会执行成功，因为左表重复键不影响多对一合并。
4.3 第二步：关联商品表
继续把商品名称和标价合并进来。这次是在上一步结果上继续操作，而不是拿原 orders 去和 products 合并，不然 user 相关列就丢了：
python复制step2 = pd.merge(step1, products, on='product_id', how='left')
print(step2)
输出：
text复制 order_id user_id product_id quantity name city product_name price
0 1001 1 101 1 小明 北京 手机 5000
1 1002 2 102 2 小红 上海 耳机 200
2 1003 2 101 1 小红 上海 手机 5000
3 1004 4 103 1 小美 深圳 充电宝 89
4 1005 1 102 3 小明 北京 耳机 200
现在每一行订单都带上了用户信息和商品信息，可以直接算销售额：
python复制step2['amount'] = step2['price'] * step2['quantity']
4.4 合并后的数据校验三板斧
合并完成不代表合并正确。我每次合并后都会做三件事：
- 看行数变化。合并后行数和预期是否一致？如果左边是主表且右表键唯一，行数应当等于左表行数。
- 看空值分布。
step2.isna().sum()能迅速看到哪一列有缺失，正常情况下name、city都不该有 NaN。 - 看关键列类型。
step2.dtypes检查合并后是不是把数值列变成了字符串。
如果你在合并时加了 indicator=True，再用 value_counts('_merge') 检查一下，匹配状况一目了然。
4.5 保存结果
宽表做完，保存成文件给下游用：
python复制# 保存为 CSV
step2.to_csv('订单宽表.csv', index=False)
# 保存为 Excel
step2.to_excel('订单宽表.xlsx', index=False)
注意 to_excel 需要装 openpyxl 或 xlsxwriter，第一次用报错的话先补一个包。
5. 初学者最容易踩的五个坑：附排查速查表
5.1 键的数据类型不一致：合并结果全是 NaN
这是最常见的“玄学”问题：明明有匹配值，merge 出来的关键列却全是 NaN。原因通常是连接键的类型不一样。比如订单表的 user_id 是 int64，用户表的 user_id 因为某些原因被读成了 object（字符串）。数值 1 和字符串 '1' 在 pandas 里不相等，merge 就匹配不上。
排查方法：
python复制print(orders['user_id'].dtype)
print(users['user_id'].dtype)
如果类型不同，统一转换：
python复制orders['user_id'] = orders['user_id'].astype(str)
users['user_id'] = users['user_id'].astype(str)
这一步通常能直接解决问题。如果原本是数值型，但带小数，比如 1.0 和 1，也需要先统一成整数或字符串再合并。合并前确认键的 dtype，是成本最低的避免踩坑方式。
5.2 键重复导致行数暴涨
前面笛卡尔积里讲过，两边键都重复时行数会成倍增加。实际业务里常见的情况是：用户表里同一个用户出现多条记录（可能是渠道信息重复），而你毫不知情，一合并订单明细就翻倍了。
合并前后对比行数是第一道防线。另外用 duplicated 提前检查：
python复制print(users['user_id'].duplicated().sum())
如果右表键有重复，先搞清楚为什么重复，再决定是去重还是保留多条。千万不要为了行数不变而盲目 drop_duplicates()，要看业务上需要保留哪条记录。
5.3 NaN 键的“神秘”行为：NaN 不会匹配 NaN
如果你画了一个 key 里包含 NaN 的表，再去合并，会发现 NaN 行不会互相匹配。比如左表有一行 key=None，右表也有一行 key=None，merge 之后并不会匹配上，而是各算各的缺失值。这是 pandas 的默认行为，因为 NaN 不等于任何值。
解决的办法是在合并前把缺失键填充成有效值，比如 fillna('未知')，或者干脆把这些行剔除。
5.4 报错 MergeError 或 KeyError 怎么办
KeyError 通常是 on 指定的列名写错了，或者在其中一个表里根本不存在。解法：打印 df.columns 检查拼写。
MergeError 大多是 validate 校验不通过，比如你声明 one_to_one，但实际是 many_to_many。解法：按前面 2.5 的说法，先弄清楚左右表的键重复情况，选择正确的 validate 值。
5.5 大表合并内存爆炸怎么办
pandas 做 merge 时会把两个表加载到内存，数据一大内存直接飙升。我的经验是分三步优化：第一，只保留合并需要的列，别把几十列无关字段全拉进来；第二，能转成 category 类型的分类列提前转换，能省不少内存；第三，如果数据真的大到一张表几个 G，建议直接用 dask.dataframe 或者 polars 的 join，思路一样，但底层是分布式或并行处理，不会 OOM。
5.6 常见问题速查表
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| merge 后行数增加 | 连接键有重复 | 查 duplicated()，去重或确认是否要笛卡尔积 |
| 结果全是 NaN | 键 dtype 不一致 | astype 统一类型，确认 int/str 一致 |
| 报 MergeError | validate 设置与实际关系不符 | 明确 one/many 关系，修正 validate |
| 报 KeyError | 连接的列不存在 | df.columns 检查列名拼写 |
列名出现 _x、_y |
两边有同名列 | 用 suffixes 自定义后缀 |
| 匹配率低 | 键里大量 NaN | 处理缺失键后再合并 |
5.7 别把 pandas 的 merge 和 Git 的 merge 搞混
这个坑特别有意思。用搜索工具搜“merge 操作”，很容易搜到一堆“IDEA 中如何回退 merge 操作”“pre-receive hook 报错”“vcs coverage merge”之类的内容。这些其实是 Git 版本控制里的分支合并，和 pandas 的 DataFrame.merge() 是两个完全不同的概念。我见过有人拿 Git 的报错思路去排查 pandas 合并问题，折腾半天毫无进展。搜问题时记得限定关键词，比如“pandas DataFrame merge 教程”，看到 pre-receive hook、版本分支这些字样，直接换结果。
6. 当需求升级：merge 系列还有哪些好用操作
6.1 merge_ordered：带顺序的合并
pd.merge_ordered() 适合处理时间序列数据。它会按照时间键把两个表合并起来，同时保留整体顺序，还能用 fill_method 做前向填充。
python复制left = pd.DataFrame({
'date': ['2024-01-01', '2024-01-03'],
'a': [1, 3]
})
right = pd.DataFrame({
'date': ['2024-01-02', '2024-01-03'],
'b': [2, 4]
})
res = pd.merge_ordered(left, right, on='date', how='outer', fill_method='ffill')
print(res)
输出：
text复制 date a b
0 2024-01-01 1.0 NaN
1 2024-01-02 1.0 2.0
2 2024-01-03 3.0 4.0
注意 a 列在 1 月 2 日被填充成了上一行的 1.0，这就是 fill_method='ffill' 的效果。适合处理业务分析里的“按日期对齐后补齐最近值”的需求。
6.2 merge_asof：做“最近时间”匹配
merge_asof() 是我经常在交易数据分析里用的函数。它的场景是：一张表记录的是下单时间，另一张表记录的是报价时间，你想知道每笔订单下单那一刻最近的报价是多少。
python复制quotes = pd.DataFrame({
'time': ['2024-01-01 09:30:05', '2024-01-01 09:30:15'],
'price': [100, 101]
})
trades = pd.DataFrame({
'time': ['2024-01-01 09:30:00', '2024-01-01 09:30:10'],
'qty': [10, 5]
})
quotes['time'] = pd.to_datetime(quotes['time'])
trades['time'] = pd.to_datetime(trades['time'])
res = pd.merge_asof(
trades.sort_values('time'),
quotes.sort_values('time'),
on='time',
direction='backward'
)
print(res)
输出：
text复制 time qty price
0 2024-01-01 09:30:00 10 NaN
1 2024-01-01 09:30:10 5 100.0
第一笔单时间是 09:30:00，早于任何报价，所以价格是 NaN；第二笔单时间是 09:30:10，匹配到 09:30:05 的报价 100，而不是 09:30:15 的未来报价。这个函数要求两个表都先按时间排序，否则结果不对。
6.3 更复杂的关系：自连接和分组合并
自连接是“一张表和自己合并”的技巧，通常用于提取层级关系。比如员工表里有 emp_id 和 manager_id，你可以把员工表分别当作“员工表”和“经理表”做一次 merge，得到每个员工的经理姓名。
python复制emp = pd.DataFrame({
'emp_id': [1, 2, 3],
'name': ['张三', '李四', '王五'],
'manager_id': [None, 1, 1]
})
result = pd.merge(
emp,
emp[['emp_id', 'name']].rename(columns={'emp_id': 'manager_id', 'name': '经理姓名'}),
on='manager_id',
how='left'
)
这种写法的关键是把同一张表复制成两份，并用 rename 调整列名，避免列名冲突。
6.4 给在实训平台刷题的同学一句话
最近很多高校的 Python 课程都用在线实训平台布置作业，像“pandas 初体验”“pandas 基本操作”“pandas 数据结构创建”这些题目，后面基本都会进阶到数据表合并。如果你正在做这类题被 merge 卡住，先别急着怀疑题目错了，按第 5 节里的排查顺序走一遍：查 dtype、查重复键、查 NaN、查列名拼写。这四步能解掉八成以上的报错。
我个人在实际操作中的体会是：merge 的每一个报错，其实都在提醒你“对数据结构的理解还不够”。把表的主键、粒度、连接方向想清楚，merge 就是一行代码的事；想不清楚，所有参数都改一遍也救不了。合并的时候多打印几个 shape 和 head()，比事后猜错多少回都强。最后再分享一个小技巧：任何 merge 做完，先 result.shape 和 result.isna().sum() 各看一眼，再谈下一步分析。