rename(columns={}) 中字典键不存在时静默失败，不报错也不警告；需先检查列名是否存在、是否重复，并注意返回新 DataFrame 而非原地修改，推荐显式赋值而非 inplace。

用 rename(columns={}) 改列名时字典键不存在会静默失败

如果你传进 rename(columns={}) 的字典里，某个 key（比如 'A'）在 DataFrame 里根本不存在，Pandas 不会报错，也不会警告——它就当没这回事，对应列名照旧。这是最常踩的坑：改了但没生效，还找不到原因。

• 先确认列名是否存在：df.columns.tolist()，注意是否含空格、大小写、不可见字符
• 如果列名是 ' A '，而你写 {'A': 'B'}，匹配不上
• 临时加个检查：用 set({'A', 'C'}) - set(df.columns) 快速看哪些要改的列不在

rename(columns={}) 是返回新 DataFrame，不是原地修改

默认情况下 rename() 不改变原 df，而是返回副本。直接打印或链式调用时容易误以为改成功了，结果后续操作还在用旧列名。

• 要么显式赋值：df = df.rename(columns={'A': 'B'})
• 要么加 inplace=True 参数：df.rename(columns={'A': 'B'}, inplace=True)（但注意：Pandas 2.0+ 已弃用 inplace，推荐前者）
• 链式调用时务必确认每一步返回的是你想要的结构，比如 df.rename(...).groupby('B').sum() 才安全

批量改名别硬写大字典，用函数更灵活

当你要把所有列名转小写、去空格、加前缀，或者按规则映射（比如 'col_1' → 'feature_1'），硬写 {'col_1': 'feature_1', 'col_2': 'feature_2'} 易错且难维护。

• 用函数： df.rename(columns=str.lower) 或 df.rename(columns=lambda x: x.strip().replace(' ', '_'))
• 函数方式能自动适配新增列，也避免漏写 key；字典方式只作用于明确列出的列
• 性能上无明显差异，但函数写法在动态场景（如 ETL 流程中列名不固定）下更鲁棒

列名重复时 rename() 会出问题，得先处理重名列

如果原始 DataFrame 有重复列名（比如两个 'A'），rename(columns={'A': 'B'}) 只会改第一个匹配到的，第二个不动，而且不会提示。这种 DataFrame 本身就不规范，但真实数据里真会出现（尤其从 Excel 多表合并来的时候）。

• 先检查：df.columns.duplicated().any()
• 修复建议：用 df.columns = pd.RangeIndex(len(df.columns)) 重置为数字索引，再按位置重命名
• 或用 df.groupby(df.columns, axis=1).sum() 合并同名列（前提是数值型且语义允许）

列名是元数据层面的“契约”，一旦错位，下游所有计算都可能跑偏。字典映射看着简单，但 key 是否存在、是否唯一、是否被覆盖、是否原地生效——每个点都卡在调试的临界点上。