FastAPI接收前端文件上传至Azure Blob Storage报错排查

前端错误修复 #

你当前前端代码的核心问题是手动给请求设置了Content-Type头。发送FormData格式的请求时，必须让浏览器自动生成带boundary边界标识的multipart/form-data请求头，手动设置会丢失边界参数，后端完全无法解析表单内的文件数据，直接删除自定义headers配置即可。
修复后的前端代码：

async function handleSubmit(){
    const formdata = new FormData();
    formdata.append("file", file[0]);
    // 移除手动设置的headers，不要自定义Content-Type
    const res = await axios.post("/uploadfile", formdata);
    console.log(res);
}

FastAPI两种文件接收方式差异 #

• file: bytes = File()：会将整个文件全量加载到服务端内存，仅适合小文件场景。该方式只能拿到文件的纯二进制内容，不包含原始文件名、文件MIME类型等元信息，你之前上传到Blob后缺后缀、缺content_type，就是因为没有额外传递这些元数据。
• file: UploadFile：FastAPI封装的专用文件接收类，底层采用内存+磁盘临时文件的缓冲机制，大文件不会占满服务端内存，自带filename（原始文件名含后缀）、content_type（文件MIME类型）、类文件操作接口，是文件上传场景的首选方案。

后端代码修复 #

你原有后端代码存在3个明确问题：

1. 调用UploadFile的read()方法时没有加await，拿到的是协程对象而非实际的二进制文件内容，传入Azure SDK会直接报类型错误
2. Azure Blob SDK的upload_blob()方法默认不允许覆盖同名Blob，同名文件上传会直接报冲突错误
3. 函数标记为async但内部全是同步IO调用，高并发场景会阻塞服务事件循环，中小流量场景直接正常调用即可，无需强行包装为异步。

推荐实现（UploadFile版本） #

from fastapi import FastAPI, UploadFile
from azure.storage.blob import BlobServiceClient, ContentSettings

app = FastAPI()
# 建议将连接字符串、容器名放到配置项统一管理，不要硬编码在函数内
AZURE_STORAGE_CONN_STR = "你的Azure存储账户连接字符串"
BLOB_CONTAINER_NAME = "notes"

@app.post("/uploadfile")
async def create_upload_file(file: UploadFile):
    # 异步读取文件二进制内容，必须加await
    file_content = await file.read()
    
    # 初始化Blob客户端
    blob_service_client = BlobServiceClient.from_connection_string(AZURE_STORAGE_CONN_STR)
    blob_client = blob_service_client.get_blob_client(
        container=BLOB_CONTAINER_NAME, 
        blob=file.filename # 直接用上传的原始文件名作为Blob名
    )
    
    # 配置文件类型，上传时开启覆盖同名文件
    content_settings = ContentSettings(content_type=file.content_type)
    blob_client.upload_blob(file_content, content_settings, overwrite=True)
    
    return {"code": 0, "msg": "上传成功", "filename": file.filename}

bytes接收版本补充实现 #

如果你坚持用file: bytes = File()的方式接收，需要前端额外通过FormData传递文件名、文件类型两个参数，否则后端无法拿到这些元信息：

1. 前端补充传参：

   formdata.append("file", file[0]);
   formdata.append("file_name", file[0].name);
   formdata.append("content_type", file[0].type);
   

2. 后端接口接收额外参数：

   from fastapi import Form
   
   @app.post("/files")
   async def create_file(
       file: bytes = File(),
       file_name: str = Form(),
       content_type: str = Form()
   ):
       blob_service_client = BlobServiceClient.from_connection_string(AZURE_STORAGE_CONN_STR)
       blob_client = blob_service_client.get_blob_client(container=BLOB_CONTAINER_NAME, blob=file_name)
       content_settings = ContentSettings(content_type=content_type)
       blob_client.upload_blob(file, content_settings, overwrite=True)
       return {"code": 0, "msg": "上传成功"}
   

常见报错对应原因 #

• 接口返回422参数校验错误：基本都是前端请求头设置错误，没有正确传递multipart/form-data格式数据，删除手动设置的Content-Type即可
• Azure SDK报类型不匹配错误：检查是否漏写await，把协程对象当成文件内容传入了
• 上传后的文件打开损坏：检查读取文件内容时是否获取到完整二进制流，不要把文件对象本身直接传给upload_blob方法
• 同名文件上传报409冲突：给upload_blob方法传入overwrite=True参数即可

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