FastAPI 支持文件上传

原创

已于 2025-07-27 08:09:37 修改 · 1.8k 阅读

标签

#fastapi #python #pdf

于 2025-05-23 16:49:16 首次发布

该文章已生成可运行项目，

FastAPI 支持文件下载
 FastAPI 支持文件上传
 Python 获取文件类型 mimetype

文章目录

1. 依赖库
2. 服务端处理
3. 客户端处理

1. 依赖库

前端上传文件文件一般都是使用 form-data，数据编码类型是 multipart/form-data，而不是 json 类型。如果你不是全属性安装 fastapi 那么需要单独的安装 form-data 相关的库：

# pip
pip install python-multipart
# poetry
poetry add python-multipart

2. 服务端处理

FastAPI 提供了 File() 和 UploadFile() 两个类用于处理文件上传。 File() 适用于小文件，而 UploadFile() 则更适合处理大文件。在文件上传时，我们建议使用异步版本的函数，这样可以避免阻塞服务器。

2.1. 上传小文件

使用 File() 时，可以通过 httpie 或 requests 库来模拟上传操作。需要注意的是，上传文件时应该使用表单而不是 JSON，这可以通过在命令中加入 -f 或 --form 参数来指定。

from fastapi import File
@app.post("/upload/small")
async def upload_small_file(small_file: bytes = File()) -> str:
    return f"file size: {
     
     len(small_file)}"

2.2. 上传大文件

对于大文件，建议使用 UploadFile ，因为它会在服务器的磁盘上创建一个临时文件对象，而不是将整个文件加载到内存中。这样可以有效避免服务器内存溢出。

from fastapi import UploadFile
import time
import os
@app.post("/upload/big")
async def upload_big_file(big_file: UploadFile= File(...)):
    filename = f"{
     
     str(time.time()).replace('.','')}-{
     
     big_file.filename}"

    local_path = "upload"
    local_file = os.path.join(local_path, filename)
    if not os.path.exists(local_path):
        os.mkdir(local_path)

    with open(local_file, "wb") as f:
        f.write(big_file.file.read())
        f.flush()

    return {
   
   
        "filename": filename,
        "filesize": big_file.size
    }

2.3. 限制文件及错误处理

from fastapi import FastAPI, File, UploadFile, HTTPException

app = FastAPI()

MAX_FILE_SIZE = 1024 * 1024 * 10  # 10MB
ALLOWED_CONTENT_TYPES = ["image/jpeg", "image/png", "application/pdf"]

@app.post("/upload/")
async def upload_file