Django上传CSV导入线索报ValueError: usecols指定列未找到如何解决

问题原因 #

该错误由pandas的列校验逻辑触发：你在pd.read_csv的usecols参数中指定的15个目标列，和上传的CSV文件的表头完全无法匹配，因此抛出异常。

解决步骤 #

1. 核对CSV表头 #

直接打开你要上传的CSV文件，检查第一行的表头是否符合以下要求：

• 名称、空格、大小写和代码usecols中的写法完全一致，比如不能把StreetNumber写为Street Number，也不能把Zip Code写为ZipCode
• 表头前后没有隐藏的空格，比如'Owner First Name '（尾部带空格）和'Owner First Name'会被判定为不同的列

2. 加调试代码定位差异 #

如果肉眼看不出问题，可以临时替换views中的读取逻辑，打印CSV的实际表头：

for d in data:
    # 仅读取前2行获取表头，不指定usecols
    df_test = pd.read_csv(d, dtype='str', nrows=2)
    # 输出实际表头和期望表头的对比，直接访问上传接口就能看到结果
    return HttpResponse(f"CSV实际表头：{list(df_test.columns)} <br> 期望匹配的表头：{['Owner First Name','Owner Last Name','StreetNumber','StreetName','State','Zip Code','Bdrms','Legal Description','Sq Ftg','Address','Orig Ln Amt','Prop Value','Equity','Email','Cell']}")

拿到实际表头后，要么修改CSV的表头和代码一致，要么修改代码中usecols的取值和CSV一致即可。

3. 新增容错逻辑（可选） #

可以在校验通过后再执行导入逻辑，避免直接抛出错误：

required_cols = [
    'Owner First Name',
    'Owner Last Name',
    'StreetNumber',
    'StreetName',
    'State',
    'Zip Code',
    'Bdrms',
    'Legal Description',
    'Sq Ftg',
    'Address',
    'Orig Ln Amt',
    'Prop Value',
    'Equity',
    'Email',
    'Cell'
]
for d in data:
    df_test = pd.read_csv(d, dtype='str', nrows=2)
    # 校验缺失列
    missing_cols = [col for col in required_cols if col not in df_test.columns]
    if missing_cols:
        return render(request, 'admin/src/tabs/fresh_leads.html', {
            'message': 1,
            'error_msg': f'CSV缺少以下必填列：{"、".join(missing_cols)}'
        })
    # 校验通过再正常读取全量数据
    df = pd.read_csv(d, dtype='str', usecols=required_cols)
    # 后续原有逻辑不变

额外优化点 #

你当前模型中的字段配置有两处不合理：

• updated_date字段应该用auto_now=True而非auto_now_add=True，这样每次更新数据时会自动刷新时间
• deleted_date字段不要设置auto_now_add=True，建议设置null=True, blank=True，只有数据被删除时再写入时间

内容的提问来源于stack exchange，提问作者djangodeveloper