多进程并发调用 pandas.to_csv(..., mode='a') 不安全，因'a'模式仅保证单次write原子性，而to_csv需多次系统调用，导致内容交错、表头重复、记录截断或I/O错误；应改用portalocker加锁后手动写入CSV字符串。
直接用 pandas.to_csv(..., mode='a') 多进程并发写入同一文件必然出错，内容会交错、截断或丢失——这不是 pandas 的问题，而是操作系统文件 I/O 模型决定的。
为什么 pandas.to_csv(mode='a') 在多进程下不安全
pandas 的 to_csv 底层仍是调用 Python 的 open(..., 'a') + f.write()，而 'a' 模式只保证内核级单次 write() 系统调用的原子性。但 to_csv 通常要写表头、多行数据、换行符、编码 BOM 等，整个过程分多次系统调用。多个进程同时执行，就会出现：
- 两行 CSV 数据挤在同一行（如
id,name\n1,a和2,b\n写成id,name\n1,a2,b\n） - 表头被重复写入多次，破坏文件结构
- 某进程写到一半被中断，留下半截记录（尤其在 Windows 上更常见）
-
OSError: [Errno 5] Input/output error或BrokenPipeError（NFS 或容器挂载卷上高频出现）
推荐方案：用 portalocker 加锁 + 手动 write，绕过 pandas.to_csv
不要让每个进程都调用 to_csv；改用锁保护的纯文本写入，把格式化交给 pandas，写入交给受控的底层 I/O：
- 每个进程先用
pandas.DataFrame.to_csv(None, index=False)生成字符串（不写磁盘），保留换行和逗号逻辑 - 再用
portalocker对文件加排他锁，f.write()+f.flush()+os.fsync(f.fileno()) - 锁粒度控制在“单次写入”级别，避免长时阻塞；不要在整个 DataFrame 处理过程中持锁
- 务必使用
encoding='utf-8'显式指定，否则 Windows 下容易因默认编码不一致导致乱码
示例关键片段：
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
立即学习“Python免费学习笔记（深入）”；
import portalocker import pandas as pd <p>def safe_append_csv(df, filepath): csv_str = df.to_csv(None, index=False, header=False) # 不带表头，避免重复 while True: try: with open(filepath, 'a', encoding='utf-8') as f: portalocker.lock(f, portalocker.LOCK_EX | portalocker.LOCK_NB) f.write(csv_str) f.flush() os.fsync(f.fileno()) portalocker.unlock(f) break except portalocker.LockException: time.sleep(0.1) # 短暂退避重试
替代思路：用 multiprocessing.Pool 的 callback 统一写入
如果数据可分块处理，更适合把写入完全剥离到主进程，避免子进程碰文件：
- 子进程只做计算，返回
df或list of dict - 主进程用
pool.apply_async(..., callback=append_to_file)收集结果并串行写入 - callback 函数内部仍需加锁（因为多个 callback 可能并发触发），但至少规避了子进程文件句柄继承问题（尤其 Windows）
- 注意：callback 运行在主进程线程中，不能直接用
threading.Lock保护文件，必须用portalocker或flock
绝对要避开的坑
这些做法看似省事，实际线上必崩：
- 用
multiprocessing.Manager().dict()或Queue把所有数据攒到内存再写——OOM 风险极高，且失去流式处理优势 - 用
to_csv(..., mode='a', header=False)并幻想 'a' 模式能兜底——它只管偏移量，不管内容语义 - 在子进程中用
threading.Lock——进程间不共享内存，该锁完全无效 - 依赖
os.open(..., os.O_APPEND | os.O_EXCL)——O_EXCL对已有文件直接报错，根本加不了锁
真正难的不是写几行代码，而是意识到：文件不是变量，锁不是装饰器，to_csv 不是原子操作。只要有一个进程没走加锁路径，整份日志就不可信。
