FastAPI接口仅接收单个文件：如何实现多文件接收？

你的问题出在参数类型定义上，Union[UploadFile, List[UploadFile]]会让FastAPI无法正确识别多文件上传场景——当用同一个字段名上传多个文件时，它会默认覆盖前面的文件，只保留最后一个。

正确的端点写法 #

直接将参数类型定义为List[UploadFile]，FastAPI会自动将同名字段的所有上传文件收集为列表：

from fastapi import APIRouter, File, UploadFile, JSONResponse
from typing import Optional, List

router = APIRouter()

@router.post("/process_files")
async def process_files(files: Optional[List[UploadFile]] = File(None)):
    print(f"\nReceived files count: {len(files) if files else 0}")
    if files:
        for file in files:
            print(f"File name: {file.filename}")
    return JSONResponse(status_code=200, content={
        "status": "completed", 
        "message": f"processed {len(files) if files else 0} files"
    })

Postman上传注意事项 #

在Postman中发送请求时，要确保所有文件的Key值一致（比如都设为files），这样FastAPI才能将它们识别为同一个列表参数的内容：

• 选择form-data格式
• 多次添加File类型的字段，每个字段的Key都填files，然后分别选择要上传的文件

为什么原写法失效？ #

Union[UploadFile, List[UploadFile]]的定义会让FastAPI优先尝试解析为单个UploadFile对象。当你上传多个同名字段的文件时，它会把后续文件当作对前一个的覆盖，最终只保留最后一个文件，而不会将它们打包成列表。

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