这篇文章能帮你解决什么- 普通表单字段怎么接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_okTrue) 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_code500, detailfFile 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_code413, detailFile 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} # 文件头最少读这么多个字节就够判断了