解决 DataFrame 无 append 方法错误

关键变更通知
在 pandas 2.0 及以上版本中，DataFrame.append() 方法已被正式移除

问题描述

当尝试使用 .append() 方法向 pandas DataFrame 添加新行时出现错误：

# 错误示例
df = pd.DataFrame(df).append(new_row, ignore_index=True)

# 错误信息
AttributeError: 'DataFrame' object has no attribute 'append'

即使确认代码在旧版 pandas 中有效，此错误表明您在使用已移除的 API 方法。

错误原因

自 pandas 2.0 版本起，官方完全移除了 DataFrame.append() 方法。主要原因是：

1. 与 Python 原生 list.append() 的命名相似但行为不同（非原地操作）
2. 低效的重复拼接操作导致 O(n²) 的时间复杂度
3. 易引发误用，尤其在循环中逐行添加数据时性能极差

推荐的解决方案

✅ 方案1：使用 concat 添加单行

# 将字典包装为新 DataFrame 后连接
new_df = pd.DataFrame([new_row])
df = pd.concat([df, new_df], ignore_index=True)

✅ 方案2：使用 loc 添加单行（注意限制）

# 仅在索引是 RangeIndex 时有效
df.loc[len(df)] = new_row  # 新增行索引 = 当前长度

<warning> **重要警告** loc 方法仅适用于 RangeIndex 索引！如果存在自定义索引或不连续索引，请使用 `concat` 方案 </warning>

✅ 方案3：批量添加多条数据（最佳实践）

data_list = []  # 初始化空列表

for item in data_source:  # 模拟数据生成循环
    # 收集字典数据到列表（非 DataFrame！）
    data_list.append({
        'column1': value1,
        'column2': value2
    })
  
# 循环结束后一次性创建 DataFrame
new_data = pd.DataFrame(data_list)
df = pd.concat([df, new_data], ignore_index=True)

为什么需要改变方法？

性能对比测试

方法	添加 10,000 行耗时	时间复杂度
concat 单次批量处理	≈0.02 秒	O(n)
循环中使用 loc	≈30 秒	O(n²)
循环中使用 concat	≈15 秒	O(n²)

测试数据基于标准开发环境，实际耗时因硬件而异

设计哲学差异

错误方案警告

# 危险！禁止使用内部方法
df = pd.DataFrame(df)._append(new_row, ignore_index=True)  # 禁止！

<danger> **不推荐的解决方案** 任何使用 `_append()` (带下划线前缀) 的方法都是**内部 API**： 1. 未在官方文档中公开 2. 可能在后续版本中无预警变更 3. 违反 pandas 使用规范 </danger>

总结指南

场景	推荐方案	代码示例
添加单行数据	pd.concat() + 单行 DataFrame 包装	pd.concat([df, pd.DataFrame([row])])
添加多行数据	列表收集 + 一次 concat	见方案3完整代码
确认索引连续	df.loc[len(df)] = ...	df.loc[len(df)] = {'col':'val'}
在循环中添加数据 ❌	绝对避免	使用临时列表替代 DataFrame 操作

终极建议：在数据处理流程中，始终优先使用列表收集数据，最后用 pd.concat() 或 pd.DataFrame() 一次性构建 DataFrame。此方案兼具代码安全性与执行效率，符合 pandas 官方最佳实践。