Unix系统下FastAPI上传Excel文件校验失败问题求助

问题场景 #

实现了FastAPI上传并校验Excel文件的功能，相关代码如下：

路由代码 #

from fastapi import APIRouter, UploadFile,File, HTTPException, status, Depends
from fastapi.responses import HTMLResponse
from app.api.deps import get_curret_admin
from app.schemas.admin import Admins
from app.core.verify_file import check_excel

router = APIRouter()

#Upload Excel File
@router.post(
    path="/api/uploadfile/",
    status_code=status.HTTP_200_OK,
    summary="Upload a excel file",
    tags= ["Files"]
)
async def upload_file(
        file: UploadFile,
        admin: Admins= Depends(get_curret_admin)
    ):
    if not check_excel(file.file):
        raise HTTPException(status_code=400, detail="El archivo no es de tipo Excel")
    return HTMLResponse("El archivo ha sido subido correctamente")

校验代码 #

from openpyxl import load_workbook

def check_excel(file):
    try:
        wb= load_workbook(file)
        return True
    except:
        return False

问题现象：功能在Windows系统运行正常，但在Linux/macOS（Unix类系统）下无法识别任何Excel文件，所有文件均被判定为非Excel类型。

原因分析 #

核心问题出在文件指针位置：

• Windows系统中，UploadFile对应的类文件对象指针默认停留在文件起始位置，load_workbook能正常读取完整文件内容。
• Unix类系统中，FastAPI接收文件时可能已对文件进行预读取（比如检测MIME类型、获取文件大小），导致文件指针移动到文件末尾。此时load_workbook从当前指针位置开始读取，无法获取Excel文件的有效头信息，触发异常后返回False。

解决方案 #

1. 重置文件指针到起始位置 #

在调用校验函数前，将文件指针重置到文件开头。由于FastAPI的UploadFile是异步对象，需使用await file.seek(0)完成指针重置：

修改后的路由代码：

from fastapi import APIRouter, UploadFile,File, HTTPException, status, Depends
from fastapi.responses import HTMLResponse
from app.api.deps import get_curret_admin
from app.schemas.admin import Admins
from app.core.verify_file import check_excel

router = APIRouter()

#Upload Excel File
@router.post(
    path="/api/uploadfile/",
    status_code=status.HTTP_200_OK,
    summary="Upload a excel file",
    tags= ["Files"]
)
async def upload_file(
        file: UploadFile,
        admin: Admins= Depends(get_curret_admin)
    ):
    await file.seek(0)  # 重置文件指针到起始位置
    if not check_excel(file.file):
        raise HTTPException(status_code=400, detail="El archivo no es de tipo Excel")
    return HTMLResponse("El archivo ha sido subido correctamente")

2. 优化校验函数的异常捕获（可选） #

避免使用裸except捕获所有异常，改为捕获openpyxl特定的无效文件异常，提升校验准确性：

修改后的校验代码：

from openpyxl import load_workbook
from openpyxl.exceptions import InvalidFileException

def check_excel(file):
    try:
        wb = load_workbook(file, read_only=True)  # 使用read_only模式提升性能
        return True
    except InvalidFileException:
        return False

额外说明 #

如果后续还需要对上传的文件进行其他操作（比如读取内容），建议在操作前再次重置文件指针，避免因指针位置问题导致读取异常。

内容的提问来源于stack exchange，提问作者Wiskani