FastAPI 文件上传避坑全指南：分块存盘、类型校验与安全兜底

这篇文章能帮你解决什么？

- 普通表单字段怎么接，Form(...)的正确打开方式

- 单文件和多文件上传的实战写法，以及异步读取的坑

- 文件大小限制怎么做才安全

- 小文件与大文件在内存处理上的本质区别，什么时候该落盘

🧩 第一部分：先搞懂表单数据怎么接

好，咱们先来最简单的场景。前端提交一个普通登录表单，用户名和密码。
很多人一上来就用Form(...)，但不知道为什么非要用它，不用行不行？

你可能会问：FastAPI 不是自己就能解析 JSON 吗？
对啊，但表单数据是application/x-www-form-urlencoded或multipart/form-data，不是 JSON。
你得明确告诉 FastAPI：这个字段从表单里拿，不是从路径参数或查询字符串里来。

from fastapi import FastAPI, Form app = FastAPI() @app.post("/login") async def login( username: str = Form(...), password: str = Form(...) ): return {"user": username}

注意那个Form(...)里的三个点，代表必填。如果你想给默认值，就直接Form("guest")。

可别偷懒用 Optional 加 None 又不设 Form 默认值，如果前端不传这个字段，直接 422，又要排查半天。

📁 第二部分：单文件上传，不止 UploadFile 那么简单

接下来重点来了，文件上传。

FastAPI 给了咱们UploadFile，这货比 Starlette 原生的UploadFile好用不少，自带异步接口。

from fastapi import FastAPI, UploadFile, File @app.post("/upload") async def upload_file(file: UploadFile = File(...)): contents = await file.read() return {"filename": file.filename, "size": len(contents)}

这里有个超容易翻车的点：就是await file.read()会把整个文件内容读进内存。
你要是传个几百兆的文件，内存当场就飙上去了。所以对于小文件（比如头像），这么做没问题，但要是一视同仁，没作区别判断，大文件这么来一下，那就是给服务器埋雷了。

再说个我踩过的坑：那就是文件读一次就没了。
你如果先await file.read()一次，再想读第二次时，你就拿不到东西了。要想复用，得先把内容存到变量里。

📚 第三部分：多文件上传，List 写法最省心

前端需要一次传多张图？直接把参数类型设置为List[UploadFile]就行，别自己手写循环拼装，那纯粹是给自己找活干。

from typing import List from fastapi import FastAPI, UploadFile, File @app.post("/upload-multiple") async def upload_files(files: List[UploadFile] = File(...)): for file in files: content = await file.read() # 依次处理每个文件 return {"uploaded": [f.filename for f in files]}

是不是以为这样就完了？还没完。

多文件上传时，如果某个文件出错，前面成功的文件要不要回滚？
怎么给前端返回精确的“第三个文件格式不对”这种错误？

这些都需要业务层自己设计好，FastAPI 只负责把文件对象给你。

🛡️ 第四部分：文件大小限制与安全性，别等出事了再想

官方文档里的确提到可以基于request.headers里的Content-Length做大小判断，但根据以往的经验，别完全依赖它。
客户端完全可以伪造这个头部，或者分块传输编码根本没有这个字段。

真正靠谱的做法是：

- 在网关层（Nginx）先限制一波client_max_body_size

- 在 FastAPI 应用里通过中间件或依赖，对已上传大小做累计检查

- 读文件时别一次性全读，用file.read(size)分块读，边读边写磁盘

咱直接看代码。分块存盘的核心思路就一句话：别一口吃成胖子，拿个小碗，一勺一勺舀到磁盘里。

我习惯用aiofiles这个库来做异步文件写入，避免阻塞事件循环。先装一下：

uv add aiofiles

然后上代码，假设我们要把上传的文件分块存到服务器本地：

import os import aiofiles from fastapi import FastAPI, UploadFile, File, HTTPException app = FastAPI() CHUNK_SIZE = 1024 * 1024 # 每次读 1MB，根据服务器内存调 @app.post("/upload-chunked") async def upload_chunked(file: UploadFile = File(...)): # 生成一个安全的目标路径，这里简单用原文件名，生产环境务必改成 UUID save_path = os.path.join("/tmp/uploads", file.filename) os.makedirs(os.path.dirname(save_path), exist_ok=True) try: # 用 aiofiles 以异步写方式打开目标文件 async with aiofiles.open(save_path, 'wb') as out_file: # 读第一块 chunk = await file.read(CHUNK_SIZE) while chunk: await out_file.write(chunk) chunk = await file.read(CHUNK_SIZE) except Exception as e: # 出错了要清理掉不完整的文件，别留垃圾 if os.path.exists(save_path): os.remove(save_path) raise HTTPException(status_code=500, detail=f"File save failed: {e}") return { "filename": file.filename, "saved_path": save_path }

🎯几个必须划重点的细节：

• CHUNK_SIZE别设太大也别太小。设 1MB 或 2MB 是个比较稳妥的值，太大跟一次读完没区别，太小了磁盘 I/O 频繁反而慢。这是我实测过几次后的经验值。

• 一定要异步写。如果你用同步的open()加write()，FastAPI 的主线程会被堵住，并发直接就跪了。aiofiles让整个过程保持在异步上下文里。

• while chunk:这个循环会一直跑到读不到数据为止，这正是我们想要的“流式读取”。文件再大，内存里永远只保留当前这一小块。

• 异常处理里的清理绝对不能省。上次我就偷懒没删残废文件，结果/tmp塞满了几十个写到一半的垃圾，排查了半天才发现。

• 真实项目中，save_path记得用uuid重命名，别直接用file.filename，防止路径穿越攻击。

如果你想在存盘的同时做一下大小限制检查，可以在循环里累加一个total_size，一旦超过阈值就终止并抛异常：

MAX_SIZE = 50 * 1024 * 1024 # 50MB total_size = 0 chunk = await file.read(CHUNK_SIZE) while chunk: total_size += len(chunk) if total_size > MAX_SIZE: # 注意：此时 out_file 已经写了一些数据，需要清理 await out_file.close() os.remove(save_path) raise HTTPException(status_code=413, detail="File too large") await out_file.write(chunk) chunk = await file.read(CHUNK_SIZE)

这样，不管多大的文件过来，你的内存都稳如老狗，磁盘也不会被撑爆。

最后啰嗦一句：上传文件一定要校验类型。
别光看扩展名，用python-magic或filetype库去读文件头，那种把 .exe 改成 .jpg 传上来的坏心思不能不防。

filetype纯 Python 实现，不需要系统依赖，更轻量，咱就用它。uv add filetype安装一下即可！
这里单独抽一个校验函数，方便在接口里调用：

import filetype # 只允许这些类型的图片上传 ALLOWED_MIME = {"image/jpeg", "image/png", "image/webp"} # 文件头最少读这么多个字节就够判断了