该用 pandas.melt() 而不是 pivot_table() 时，是当列名含语义（如年份、季度）需“压扁”为变量-值长格式；pivot_table() 用于宽化，误用会导致报错或错误聚合。
什么时候该用 pandas.melt() 而不是 pivot_table()
当你有一张列名代表分类（比如年份、地区、产品型号），而你想把它们“压扁”成一列变量+一列值时，melt() 是唯一自然的选择。反过来，pivot_table() 是从长变宽——如果误用它来“反向还原”，会报 ValueError: Index contains duplicate entries 或生成意外的聚合结果。
常见错误现象：直接对原始宽表调用 .pivot() 报错；或用 stack() 后忘记 reset_index()，导致索引混乱、列名丢失。
-
id_vars必须指定为不变的标识列（如['country', 'year']），漏写会导致所有列都被“熔化” -
value_vars可省略，但显式列出更安全——尤其当宽表里混有中间计算列或时间戳列时 - 不设
var_name和value_name时，默认列名是'variable'和'value'，容易和业务字段冲突
melt() 的参数怎么选：从 Excel 表头直译到代码
假设你读入的 DataFrame 表头是：['product', 'Q1_sales', 'Q2_sales', 'Q3_sales', 'Q4_sales']，想转成 product、quarter、sales 三列——这就是典型的“列名含语义”的宽表。
对应代码就是：
立即学习“Python免费学习笔记（深入）”；
df_melted = df.melt(
id_vars=['product'],
value_vars=['Q1_sales', 'Q2_sales', 'Q3_sales', 'Q4_sales'],
var_name='quarter',
value_name='sales'
)
注意：value_vars 中的字符串必须严格匹配原始列名；大小写、下划线、空格一个都不能错。如果列名是 'Q1 Sales'（带空格），就写 'Q1 Sales'，不能写成 'Q1_Sales'。
- 若季度列名是
['2022_Q1', '2022_Q2', '2023_Q1', '2023_Q2']，可先用df.filter(regex=r'_Q[1-4]$')动态提取，再传给value_vars -
var_name建议用业务术语（如'period'、'metric'），别留默认的'variable' - 如果某列本该是
id_vars但被当成数值列读入（比如'order_id'被 pandas 自动识别为int64），要提前转成str或category，否则melt()不报错但后续groupby会出问题
处理多级列名（MultiIndex）时的坑
当 Excel 或 CSV 有合并表头（例如第一行是部门，第二行是指标），pd.read_excel(header=[0,1]) 会生成 columns 为 MultiIndex 的 DataFrame。此时直接调用 melt() 会报错：TypeError: unhashable type: 'list'。
必须先展平列名，例如：
df.columns = ['_'.join(col).strip() for col in df.columns.values]
或者更稳妥地用命名规则重建：
df.columns = [f"{lev0}_{lev1}" if lev1 else lev0 for lev0, lev1 in df.columns]
- 展平后检查是否有重复列名（比如两个
'sales_total'），重复会导致melt()后数据错行 - 如果原始 MultiIndex 有明确语义（如
('revenue', 'usd')和('cost', 'usd')），展平时建议保留层级信息，如'revenue_usd'，方便后续用str.split('_')提取维度 - 不要在
melt()后立刻用pd.to_numeric()强转value列——因为value列可能混合了数字、字符串（如 “N/A”、“—”），先用pd.to_numeric(..., errors='coerce')
性能提醒：大宽表别用 stack() 替代 melt()
有人图省事写 df.set_index('id').stack().reset_index(name='value')，看起来等价，但实际慢 3–5 倍（尤其列数 > 50 时）。因为 stack() 内部走的是索引重排路径，而 melt() 是纯列向操作，C 实现更轻量。
另一个隐形成本：如果宽表有 100 列，其中 95 列要熔化，但你只写了 value_vars 里 95 个名字——手写易漏、难维护。此时推荐：
- 用
df.columns.difference(['id', 'timestamp'])动态排除 ID 列 - 或用正则筛选：
df.filter(regex=r'^(?!id|meta).*').columns.tolist() - 熔化后立刻检查
df_melted['value'].isna().sum()——宽表中常见的空单元格，在熔化后会变成大量NaN，影响后续聚合精度
最常被忽略的一点：melt() 不校验 value_vars 是否真在 df.columns 中，拼错列名只会静默跳过——务必在调用前后打印 len(df.columns) 和 len(value_vars) 对齐。
