UploadFile不适合真正的大文件上传，因其底层依赖Starlette的form解析器，会先缓存整个multipart请求体（内存或磁盘），导致超200MB时易OOM、崩溃或解析失败；而request.stream()可直读原始字节流，跳过form解析，配合MultiPartParser边流边解析并设max_form_memory_size=0，才能安全处理500MB级以上文件。
直接读 request.body() 或用 UploadFile 接收大文件，上传 500MB 就可能卡死、OOM 或触发 413 Request Entity Too Large ——这不是代码写得不对，而是默认路径根本没走流式通道。
为什么 UploadFile 不适合真正的大文件上传
UploadFile 看似支持“异步读”，但它底层仍依赖 Starlette 的 form 解析器，会把整个 multipart 请求体先缓存（内存或磁盘临时文件），再交给你。一旦文件超 200MB，Uvicorn 可能因磁盘空间不足崩溃；若前端没设 boundary 或格式错位，解析直接失败，错误信息还藏在底层日志里。
- 它不跳过 form 解析，无法跳过字段解析开销
- 即使只传一个文件字段，也会把所有 headers + boundary + 元数据全吃进缓冲区
-
await file.read()调用后，file.file已是SpooledTemporaryFile，再调用.seek(0)可能报ValueError: I/O operation on closed file
绕过 form 解析：用 request.stream() 直读原始字节流
这才是可控的起点。你放弃 UploadFile，改用 Request 对象的 stream() 方法，拿到一个异步迭代器，逐块消费原始 HTTP body —— 完全跳过 multipart 解析，也就不怕字段混乱或大小限制。
- 必须去掉所有
File、UploadFile参数，函数签名只留request: Request - 调用
request.stream()，不是await request.body()（后者会一次性加载全部） - 需手动解析 multipart boundary：从
request.headers["content-type"]提取boundary=...，再用它切分流 - 推荐用
werkzeug.formparser.MultiPartParser边流边解析，设max_form_memory_size=0强制所有内容落盘
示例关键片段：
from werkzeug.formparser import MultiPartParser
from werkzeug.datastructures import Headers
<p>@app.post("/upload/raw/")
async def raw_upload(request: Request):
content_type = request.headers.get("content-type", "")
boundary = content_type.split("boundary=")[-1].strip()
headers = Headers([("Content-Type", f"multipart/form-data; boundary={boundary}")])</p><pre class="brush:php;toolbar:false;">parser = MultiPartParser(
stream=request.stream(),
headers=headers,
max_form_memory_size=0, # 关键：禁用内存缓冲
)
async for field_name, value, filename, content_type in parser.parse():
if field_name == "file":
# value 是 bytes，直接写入目标路径或对象存储
async with aiofiles.open(f"/tmp/{filename}", "ab") as f:
await f.write(value)
上传响应提速的关键：别等全写完才返回
用户上传 2GB 文件时，你等到最后一字节落盘才返回 200 OK，体验就是“卡住”。真正的提速，是边收边确认、分段响应。
- 每收到一个完整分块（比如 8MB），就向客户端返回一个轻量
206 Partial Content响应，附带当前已接收字节数 - 前端可据此更新进度条，甚至断点续传（配合
Range和Content-Range头） - 服务端不要阻塞写磁盘：用
asyncio.to_thread(open(...).write)包裹同步 IO，避免事件循环挂起 - 避免在循环里反复
os.path.getsize()查已写大小——改用累加变量
部署层限制比代码更早拦住你
client_max_body_size 不是 FastAPI 的配置项，Uvicorn 默认只允许 100MB；Nginx 默认 1MB；Cloudflare 更是硬性卡在 100MB。你代码再流式，请求根本到不了 Python 进程就被拦截了。
- Uvicorn 启动加
--limit-concurrency 1000 --limit-max-requests 0，但核心是--proxy-headers配合 Nginx 的client_max_body_size 2g; - 若用 Nginx，务必加
proxy_buffering off;和proxy_request_buffering off;，否则它自己就把流缓存了 - 本地调试时，用
curl -F "file=@large.zip" http://localhost:8000/upload/raw/测试，别只信 Postman 的“form-data”界面，它有时悄悄转成 base64
最常被忽略的一点：boundary 必须由前端生成并透传，后端不能硬编码；而 MultiPartParser 对换行符敏感，Windows 换行（\r\n）和 Unix（\n）混用会导致解析中断——建议前端统一用 \r\n，后端不校验换行风格，只按标准 RFC 2046 切分。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
