FastAPI中UploadFile对接接收类文件对象第三方库的最佳实践

云上老周

2026-10-1

FastAPI上传文件获取类文件对象的最佳实践

核心结论

不需要访问私有`_file`属性，也不需要将文件落地到磁盘，有两种基于公开API的实现方案，适配不同场景：

方案1：直接使用`UploadFile.file`（纯Python库优先）

starlette的UploadFile暴露的file属性本身就是tempfile.SpooledTemporaryFile类型，属于标准Python类文件对象，纯Python实现的库（比如python-docx）可以直接使用，仅需要注意操作前将文件指针重置到起始位置：

import docx
from fastapi import FastAPI, File, UploadFile

app = FastAPI()

@app.post("/open-docx")
async def open_docx(upload_file: UploadFile = File(...)):
    # 重置文件指针到开头，避免读取位置异常
    upload_file.file.seek(0)
    mydoc = docx.Document(upload_file.file)
    return {"firstparagraph": mydoc.paragraphs[0].text}

方案2：转`BytesIO`（C扩展类库适配）

如果用到pdftotext这类基于C扩展实现的库，对类文件对象的兼容性要求更高，可以直接将文件内容读入内存的BytesIO对象，全程不落盘，兼容性拉满：

import pdftotext
from io import BytesIO
from fastapi import FastAPI, File, UploadFile

app = FastAPI()

@app.post("/open-pdf")
async def open_pdf(upload_file: UploadFile = File(...)):
    # 异步读取全部文件内容，写入BytesIO
    file_content = await upload_file.read()
    pdf_io = BytesIO(file_content)
    mypdf = pdftotext.PDF(pdf_io)
    return {"firstpage": mypdf[0]}