Python CSV 文件追加写入最佳实践：避免重复表头与数据冗余

本文详解如何使用 Python 的 csv 模块正确将 S3 对象元数据写入 CSV 文件，解决循环中重复写入表头、数据叠加及历史内容累积等常见问题。核心在于区分文件初始化与增量写入，并严格控制 writeheader() 和 writerow() 的调用时机。

今天我们来聊一个在 Python CSV 操作里特别容易踩的坑——从 S3 批量导出对象元数据到本地 CSV 文件时，稍不注意就会搞出“表头连数据、数据连表头”的循环叠加问题。简单说，就是每次循环都以追加模式（"a"）打开文件，然后重复写一遍表头，结果每一条记录前面都多了一行 account_id;arn；再加上追加模式不清除旧内容，多次运行脚本后，数据就像滚雪球一样成倍重复，整个文件惨不忍睹。

那么正确的姿势是什么？一句话：先把“骨架”搭好，再往里填内容。具体来说，分两步走：

• 第一次创建文件时，只写一次表头。如果后续想覆盖旧数据，就用写入模式 "w"；如果想保留历史但避免重复，可以事先检查文件是否存在，仅在新文件时写表头。
• 用 csv.DictWriter 代替手动拼接。字段名和值通过字典映射，自动对齐列，既清晰又不容易出错。

另外有两个细节必须注意：一是务必加上 newline='' 参数，这是 Python 官方文档反复强调的，否则 Windows 下会多出一堆空行；二是从 S3 读取 Body 时，返回的是字节流，如果内容本身是文本，记得显式解码（比如 .decode('utf-8')），不然写入 CSV 时会因为二进制格式而报错。

下面是一段可以直接上手的生产级代码：

import csv

# 初始化 CSV 文件（覆盖模式，确保干净起点）
with open("my_file.csv", "w", newline="") as csvfile:
    fieldnames = ["account_id", "arn"]
    writer = csv.DictWriter(csvfile, fieldnames=fieldnames, delimiter=";", quoting=csv.QUOTE_MINIMAL)
    # 写入表头（仅一次）
    writer.writeheader()

    # 遍历 S3 对象并逐行写入
    for obj in my_bucket.objects.filter(Prefix="folderpath"):
        try:
            key = obj.key
            # 注意：body 是 bytes，若需字符串请解码
            body_bytes = obj.get()["Body"].read()
            body_str = body_bytes.decode("utf-8") if isinstance(body_bytes, bytes) else body_bytes
            writer.writerow({"account_id": key, "arn": body_str})
        except Exception as e:
            print(f"跳过对象 {obj.key}，错误：{e}")
            continue  # 出错时不中断整个流程

这里有几个容易翻车的点，需要特别盯一下：

• 别把 "a"（追加模式）和 writeheader() 混着用——后者只能在新文件或清空后调用一次。
• 如果业务要求真正追加新数据（比如定时增量同步），可以先用 "r" 模式读一下文件现有行数：空文件就写表头，非空就直接用 open("my_file.csv", "a", newline="") 并跳过 writeheader()。
• delimiter=";" 要与 Excel 或其他工具的分隔符设置保持一致；如果字段里可能包含分号或换行符，csv.QUOTE_MINIMAL（默认值）会自动加引号保护。
• 生产环境最好加上异常捕获和日志，别让一个坏掉的 S3 对象毁了整个导出任务。

总结下来，CSV 写入的本质是结构化流式输出，而不是简单地“拼接文本”。把 csv.DictWriter 的生命周期管理好——初始化、写表头、写数据——就能彻底告别重复与污染的问题。