不能直接在async函数里用openpyxl或pandas.to_excel，因为二者均为同步阻塞调用，会卡住event loop；即便用await asyncio.to_thread()包装，Excel写入本质是CPU密集型操作，受GIL限制，线程无法真正并行，反而降低性能；必须改用multiprocessing+asyncio.run_in_executor组合，将Excel构建移至独立子进程执行。
为什么不能直接在 async 函数里用 openpyxl 或 pandas.to_excel
因为 openpyxl 和 pandas.DataFrame.to_excel 都是同步阻塞调用，会直接卡住 event loop。哪怕你用 await asyncio.to_thread() 包一层，也只是把 IO 等待挪到线程池——但 Excel 写入本质是 CPU 密集型（尤其是带样式、多 sheet、公式或大表格），线程无法真正并行，GIL 会让性能不升反降。
必须用 multiprocessing + asyncio.run_in_executor 的组合
核心思路：把 Excel 构建逻辑完全移出主线程，在独立子进程中执行，再通过 run_in_executor 把进程启动包装成 awaitable。注意不是用 Process 手动管理，而是靠 concurrent.futures.ProcessPoolExecutor 统一调度。
- 定义一个顶层函数（不能是类方法或闭包），例如
generate_excel_file，接收纯数据（dict/list/DataFrame）和输出路径，返回文件路径或字节流 - 确保该函数不依赖全局状态、不引用 asyncio 对象（如 loop、task）、不调用任何异步函数
- 在 FastAPI/Starlette 的路由中这样调用：
loop = asyncio.get_event_loop() result_path = await loop.run_in_executor( process_pool, generate_excel_file, data, tmp_path ) - 进程池需提前初始化（比如在 app startup 时），避免每次请求都新建——
process_pool = ProcessPoolExecutor(max_workers=2)，worker 数建议 ≤ CPU 核心数
数据序列化限制：pandas DataFrame 不能直接传进子进程
子进程间通信靠 pickle，而 DataFrame 中若含自定义对象、lambda、本地函数或某些扩展 dtype（如 pd.ArrowDtype），pickle 会失败，报错类似 Can't pickle _thread.RLock objects 或 AttributeError: Can't pickle local object。
- 导出前先调用
df.copy(deep=True).reset_index(drop=True)清除隐式引用 - 用
df.astype({col: 'string' for col in df.select_dtypes('object').columns})统一 object 列为 string，避免混合类型导致的 pickle 异常 - 更稳妥的做法：传入原始 dict-of-lists 或 JSON-serializable 结构，在子进程中重建 DataFrame
- 如果必须传 DataFrame，可改用
cloudpickle替换默认 pickle，但会增加启动开销和兼容风险，不推荐线上用
临时文件路径与清理要跨进程安全
多个 worker 进程同时写同名文件会冲突，且主进程无法直接访问子进程的 tempfile.mktemp() 返回路径（它只在子进程内有效）。
立即学习“Python免费学习笔记（深入）”；
- 主进程生成唯一路径，例如
tmp_path = Path(f"/tmp/export_{uuid4().hex}.xlsx")，再传给子进程 - 子进程完成写入后，**不要**在子进程中删文件（可能被其他请求复用），由主进程统一处理后续（比如返回文件流后立即 unlink，或设 TTL 清理任务）
- 务必检查子进程异常退出时文件是否残留——建议在子进程函数末尾加
try/finally，失败时写空文件或标记状态，主进程据此判断是否重试 - Linux 下注意 /tmp 可能挂载为 tmpfs，大 Excel（>500MB）容易爆内存，应改用
/var/tmp或专用目录
