如何使用FastAPI同时上传图片文件和字符串列表参数？

问题原因 #

该问题是FastAPI处理multipart/form-data请求的默认逻辑导致的：当接口同时包含普通参数和UploadFile类型的文件参数时，FastAPI会自动将请求编码切换为multipart/form-data。这种编码下，列表类型的普通参数如果没有明确指定解析规则，会被识别为单个逗号拼接的字符串，因此你拿到的languages结果是["en,hi"]而不是拆分后的两个独立元素。
仅保留单个参数时接口正常，是因为单参数场景不会触发multipart/form-data编码，FastAPI可以正常完成列表类型的自动解析。

解决方案 #

方案1：将列表参数声明为查询参数（推荐） #

直接给languages参数添加Query装饰器，将其指定为URL查询参数，不受请求体的编码规则影响，FastAPI会自动完成列表拆分：

from fastapi import FastAPI, UploadFile, File, Query
from typing import List

app = FastAPI()

@app.post("/my-endpoint")
async def my_func(
    languages: List[str] = Query(["en", "hi"]), 
    image: UploadFile = File(...)
):
    # 此处languages已自动解析为 ["en", "hi"] 格式
    return {"languages": languages, "image_filename": image.filename}

前端调用时，将languages放在URL参数中传递即可，支持?languages=en&languages=hi或?languages=en,hi两种传参格式。

方案2：表单接收字符串后手动拆分 #

如果业务要求所有参数都放在表单体中传递，可以先用Form接收逗号拼接的字符串，再手动拆分为列表：

from fastapi import FastAPI, UploadFile, File, Form
from typing import List

app = FastAPI()

@app.post("/my-endpoint")
async def my_func(
    languages: str = Form("en,hi"), 
    image: UploadFile = File(...)
):
    # 手动拆分字符串为列表，可额外添加去重、过滤空值等逻辑
    language_list = [lang.strip() for lang in languages.split(",") if lang.strip()]
    return {"languages": language_list, "image_filename": image.filename}

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