starlette 上传文件并保存的核心做法是读取 request 对象的 file 属性,获取 uploadfile 实例后调用其 save() 方法将内容写入本地磁盘。具体实现时,需确保 html 表单的 enctype 设置为 multipart/form-data,并在路由处理函数中通过 await request.form() 解析请求体以提取文件对象。若未指定目标路径,文件将保留在内存或临时目录中;显式传入 pathlib.path 对象可控制存储位置。

如何从 multipart 请求中提取 UploadFile 对象
直接回答:通过 await request.form() 获取字典形式的表单数据,再从中取出 files 键对应的 UploadFile 实例即可。该操作会触发流式读取,但不会立即将所有内容加载到内存,适合中等大小文件。若表单中没有文件字段,files 将为空列表,此时不应调用 save() 以免报错。

from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import PlainTextResponse
import os
app = Starlette()
@app.route("/upload", methods=["POST"])
async def upload_file(request: Request):
form = await request.form()
file = form["file"]
save_path = Path("./uploads") / file.filename
save_path.parent.mkdir(parents=True, exist_ok=True)
with open(save_path, "wb") as f:
while chunk := await file.read(8192):
f.write(chunk)
return PlainTextResponse(f"Saved to {save_path}")
预期结果:当发送包含 file 字段的 POST 请求时,服务器会在当前目录创建 uploads 文件夹,并将上传内容以原始文件名保存。返回文本显示实际保存路径。若文件名含特殊字符,Path 会自动处理转义,但建议对文件名做清洗以防路径遍历攻击。
UploadFile.save() 与手动写入的区别是什么
直接回答:UploadFile.save(path) 是封装好的便捷方法,内部自动处理分块读取和二进制写入,等价于手动循环 await file.read(size) 并写入文件。区别在于前者更简洁且保证原子性写入,后者允许插入中间逻辑如校验或转换。两者底层都使用异步 I/O,性能差异可忽略,除非手动代码引入额外阻塞操作。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from pathlib import Path
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
app = Starlette()
@app.route("/upload_save", methods=["POST"])
async def upload_with_save(request: Request):
form = await request.form()
file = form["file"]
save_dir = Path("./uploads")
save_dir.mkdir(parents=True, exist_ok=True)
target = save_dir / file.filename
await file.save(target)
return JSONResponse({"status": "saved", "path": str(target)})
预期结果:调用 await file.save(target) 后,文件被完整写入 target 路径,返回 JSON 包含状态和路径字符串。若 file 为空或上传中断,save() 可能写入不完整文件,需结合业务逻辑检查文件大小或哈希值。此方式适用于大多数标准上传场景,无需关心底层缓冲策略。
如果上传的文件名为 None 会发生什么
直接回答:当客户端未提供文件名或浏览器因安全策略省略文件名时,UploadFile.filename 为 None,此时直接使用它构造路径会导致 TypeError。正确做法是先判断 filename 是否为 None,若是则生成唯一标识符如 UUID 作为文件名,避免程序崩溃。该行为源于 HTTP 规范中文件名可选性,并非 Starlette 特有限制。
import uuid
from pathlib import Path
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
app = Starlette()
@app.route("/upload_safe", methods=["POST"])
async def upload_safe(request: Request):
form = await request.form()
file = form["file"]
filename = file.filename or str(uuid.uuid4())
save_dir = Path("./uploads")
save_dir.mkdir(parents=True, exist_ok=True)
target = save_dir / filename
await file.save(target)
return JSONResponse({"status": "saved", "path": str(target), "original_name": file.filename})
预期结果:即使原始 filename 为 None,程序仍能用 UUID 生成有效路径并完成保存,返回 JSON 中包含原始名称(可能为 null)和新路径。这确保了上传流程的健壮性,避免因元数据缺失导致服务异常。开发者应在所有涉及文件名的环节加入此类防御性编程。










