FastAPI怎么实现文件上传与多文件保存-Python教程-PHP中文网

fastapi多文件上传需用list[uploadfile]接收，逐个流式保存并显式close()，重命名文件名防覆盖，确保目录安全且分层存储。

fastapi怎么实现文件上传与多文件保存

FastAPI 实现文件上传本身不难，但“多文件保存”容易在路径处理、资源释放、并发写入和错误恢复上出问题。核心不是能不能传，而是传完能不能稳稳落地。

UploadFile + List[UploadFile] 是接收多文件的唯一正确方式

别用 File() 单独套多个参数，也别试图手动解析 request.body。FastAPI 要求明确声明类型：

List[UploadFile] 是接收 multipart/form-data 中多个同名 <input type="file" name="files"> 字段的强制约定
如果前端发的是不同 name（如 file1, file2），后端必须写成多个独立参数，无法用列表统一接收
每个 UploadFile 对象自带 filename、content_type 和可异步读取的 file 属性，不要提前 .read() 除非你确定文件小

保存多文件时必须逐个 await file.read() + 显式 close()

直接 await file.read() 会把整个文件加载进内存，大文件上传时可能 OOM。更稳妥的做法是流式保存：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

用 shutil.copyfileobj(file.file, buffer)，其中 file.file 是底层 SpooledTemporaryFile 对象，支持 seek 和 read
每个文件处理完必须 await file.close()，否则临时文件不会自动清理，磁盘会被占满
推荐用 try/finally 包裹单个文件处理逻辑，避免某个文件失败导致后续文件没释放资源

示例关键片段：

for f in files:<br>    try:<br>        file_path = UPLOAD_DIR / f.filename<br>        with open(file_path, "wb") as buf:<br>            shutil.copyfileobj(f.file, buf)<br>    finally:<br>        await f.close()

UPLOAD_DIR 路径安全与并发写入风险

多文件同时上传时，如果都用原始 filename 保存，会覆盖或报错。必须做两件事：

用 os.makedirs(UPLOAD_DIR, exist_ok=True) 确保目录存在，但注意 UPLOAD_DIR 绝对不能是用户可控路径（如来自表单字段），否则有路径遍历风险
文件名必须重命名：至少加 UUID 或时间戳前缀，比如 f"{uuid.uuid4()}_{f.filename}"；原始 f.filename 只能用于提取后缀或展示，不可直写磁盘
如果上传量大，避免所有文件写到同一目录——Linux 下单目录文件过多会影响 inode 查找性能，建议按日期分层，如 uploads/2026/10/01/

最常被忽略的点是：UploadFile.file 是一个已打开的类文件对象，它背后是内存或临时磁盘缓冲，不 close() 就不会释放；而 shutil.copyfileobj 不会自动关闭源对象，这点和普通 open() 不同。