如何向FastAPI后端上传≥3GB大文件并解决422请求错误？

1. 修复422字段缺失错误 #

出现422错误的核心原因是请求未正确设置Content-Type头，FastAPI无法识别请求为multipart/form-data格式，进而无法解析出upload_file字段。

修正客户端代码，添加对应请求头（直接复用MultipartEncoder的content_type属性）：

file_name="afd.tgz"
m = MultipartEncoder(fields={"upload_file": open(file_name, 'rb')})
prefix = "http://xxx:5000"
url = "{}/v1/uploadfiles".format(prefix)
try:
    req = requests.post(
        url,
        data=m,
        headers={"Content-Type": m.content_type},  # 必须添加此行
        verify=False,
    )
    req.raise_for_status()  # 主动抛出HTTP错误便于排查问题
except Exception as e:
    print(f"上传失败: {e}")

同时需确认：

• 客户端请求URL与服务器路由匹配：服务器路由为/uploadfiles，客户端请求的是/v1/uploadfiles，若服务器未挂载/v1子路径，需调整URL或修改服务器路由配置。

2. 确保大文件流式上传（不加载到内存） #

服务器端处理 #

FastAPI的UploadFile默认采用流式处理，不会将整个文件加载到内存，只需分块写入磁盘即可：

from fastapi import FastAPI, File, UploadFile
import shutil

app = FastAPI()

@app.post("/uploadfiles")
async def uploadfiles(upload_file: UploadFile = File(...)):
    # 分块写入磁盘，避免占用过多内存
    with open(f"saved_{upload_file.filename}", "wb") as buffer:
        shutil.copyfileobj(upload_file.file, buffer)
    return {"filename": upload_file.filename}

shutil.copyfileobj默认以8KB块大小复制数据，不会一次性读取整个文件。

客户端确认 #

使用MultipartEncoder配合requests.post(data=m)本身就是流式上传模式，MultipartEncoder会逐块读取文件内容并发送，不会将3GB文件全部加载到内存，无需额外修改。

额外排查点 #

• 确认服务器已安装python-multipart依赖：FastAPI解析multipart/form-data需要该包，执行pip install python-multipart完成安装。
• 若文件超出默认请求大小限制，启动服务时可调整参数：uvicorn.run(app, host="0.0.0.0", port=5000, limit_max_requests=10*1024*1024*1024)（示例限制为10GB）。

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