第一部分先搞懂表单数据怎么接好咱们先来最简单的场景。前端提交一个普通登录表单用户名和密码。很多人一上来就用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} # 文件头最少读这么多个字节就够判断了 MAGIC_BYTES_LEN 261 def validate_file_type(file: UploadFile, allowed_mimes: set): 读文件头部魔数来判断真实类型。 这里先只读头部不消耗整个文件后面还能接着 read。 # 保证读取指针在开头不然拿不到正确头部 file.file.seek(0) head file.file.read(MAGIC_BYTES_LEN) # 读完头记得把指针复位否则后续分块读或存盘读不到完整内容 file.file.seek(0) kind filetype.guess(head) if kind is None: raise HTTPException( status_code400, detailf无法识别文件类型文件头部不是已知格式 ) if kind.mime not in allowed_mimes: raise HTTPException( status_code400, detailf不支持的文件类型: {kind.mime}只允许: {, .join(allowed_mimes)} ) return kind app.post(/upload-safe) async def upload_safe(file: UploadFile File(...)): # 先校验类型不通过直接拒绝不会在磁盘落任何东西 validate_file_type(file, ALLOWED_MIME) # 下面才开始真正的存盘逻辑…… # 这里接你分块存盘或直接 read 的代码 contents await file.read() return {filename: file.filename, size: len(contents)}这个实现里也藏着几个容易翻车的小细节file.file.seek(0)这步绝对不能漏。UploadFile.file是一个类文件对象读了头部后指针就偏移了不复位的话后续读文件会缺前面这一截导致存下来的文件损坏。这个坑我当初排查到凌晨三点。MAGIC_BYTES_LEN我习惯设 261 字节足以覆盖绝大多数格式的文件头。但像 Office 2007 那种 zip 包裹格式判断会稍微复杂一般业务用场景够用了。校验时机选在存盘动作之前这样可以第一时间拒绝恶意文件避免无效 I/O 和潜在的安全风险。filetype.guess()通过文件头魔数判断.exe改成.jpg会被揪出来这是扩展名和 MIME 欺骗搞不定的。但这种判断不是 100% 防得住所有伪装有条件再加一层病毒扫描是更安全的。 第五部分内存缓存 vs 硬盘暂存怎么选这个问题的本质其实是个取舍。对于头像、缩略图这种大概率不到 1MB 的文件你完全可以await file.read()后直接丢对象存储速度快代码也清爽。但对于用户上传的附件、视频这类可能很大的文件就得用分块读取 临时文件流的模式。Starlette 的UploadFile有个属性叫file它底层是tempfile.SpooledTemporaryFile小文件就在内存里超过一定阈值自动落盘。但这个阈值默认是 1MB你可以根据自己服务器内存情况调一下。我的选择就简单粗暴只要不是确定要转存的临时数据一律流式写硬盘免得到时候 OOM 了再后悔。