FastAPI上传文件至S3：指定路径时上传失败求助

当指定file_path上传失败但默认路径成功时，通常是以下几个原因导致，对应解决方案如下：

1. S3路径格式错误 #

S3的对象键（即file_path）不能以/开头，也不能包含未转义的非法字符（如空格）。如果传入类似/folder/file.txt的路径，会触发S3的路径解析异常。

解决方法：
对传入的file_path做格式校验，移除开头的/并替换非法字符：

# 修正路径格式：移除开头斜杠，替换空格为URL转义字符
s3_request.file_path = s3_request.file_path.lstrip('/').replace(' ', '%20')

2. S3权限不足 #

如果指定的file_path对应的前缀路径（如subfolder/）需要额外权限，而你的AWS凭证没有PutObject到该前缀的权限，会导致上传失败。比如Bucket策略仅允许上传到根目录，限制了子路径的写入权限。

解决方法：
检查S3 Bucket的权限策略，确保凭证拥有s3:PutObject权限，且资源范围包含arn:aws:s3:::your-bucket/*（而非仅根目录）。示例策略片段：

{
    "Effect": "Allow",
    "Action": "s3:PutObject",
    "Resource": "arn:aws:s3:::your-bucket/*"
}

3. 文件指针未重置 #

使用UploadFile时，文件指针可能因前置操作停留在文件末尾，导致upload_fileobj读取不到内容。虽然默认路径上传成功，但指定路径时的逻辑分支可能触发该问题。

解决方法：
在上传前强制重置文件指针到起始位置：

await file.seek(0)  # 重置文件指针到文件开头
s3_client.upload_fileobj(file.file, s3_request.bucket_name, s3_request.file_path)

4. 错误信息不完整 #

当前代码仅将ClientError转为字符串，丢失了具体错误代码（如AccessDenied、NoSuchBucket），无法精准定位问题。

解决方法：
修改ClientError捕获逻辑，提取详细错误信息：

except ClientError as e:
    error_code = e.response['Error']['Code']
    error_message = e.response['Error']['Message']
    raise HTTPException(
        status_code=500,
        detail=f"S3 Error: {error_code} - {error_message}"
    )

修改后的完整代码 #

from fastapi import FastAPI, File, UploadFile, HTTPException, Depends
from pydantic import BaseModel
from typing import Optional
from botocore.exceptions import NoCredentialsError, PartialCredentialsError, ClientError
import boto3
import uvicorn

app = FastAPI()

AWS_ACCESS_KEY = "XXX"
AWS_SECRET_KEY = "YYY"
AWS_REGION_NAME = "ap-northeast-1"


# Pydantic model for the request body
class S3UploadRequest(BaseModel):
    bucket_name: str
    file_path: Optional[str] = None  # Make file_path optional


@app.post("/upload/")
async def upload_file_to_s3(
        s3_request: S3UploadRequest = Depends(),
        file: UploadFile = File(...)
):
    """
    Upload a file to an S3 bucket.

    :param s3_request: S3UploadRequest. Contains the bucket name and file path.
    :param file: UploadFile. The file to upload.
    """
    try:
        s3_client = boto3.client(
            's3',
            aws_access_key_id=AWS_ACCESS_KEY,
            aws_secret_access_key=AWS_SECRET_KEY,
            region_name=AWS_REGION_NAME
        )

        # Set default file path if not provided
        if s3_request.file_path is None:
            s3_request.file_path = file.filename
        else:
            # 修正路径格式：移除开头斜杠，替换空格
            s3_request.file_path = s3_request.file_path.lstrip('/').replace(' ', '%20')

        # 重置文件指针到起始位置
        await file.seek(0)
        
        # Upload file to S3
        s3_client.upload_fileobj(file.file, s3_request.bucket_name, s3_request.file_path)

        return {
            "message": f"File '{file.filename}' uploaded successfully to bucket '{s3_request.bucket_name}' at '{s3_request.file_path}'"}

    except NoCredentialsError:
        raise HTTPException(status_code=403, detail="AWS credentials not found.")
    except PartialCredentialsError:
        raise HTTPException(status_code=403, detail="Incomplete AWS credentials.")
    except ClientError as e:
        error_code = e.response['Error']['Code']
        error_message = e.response['Error']['Message']
        raise HTTPException(
            status_code=500,
            detail=f"S3 Error: {error_code} - {error_message}"
        )


if __name__ == "__main__":
    uvicorn.run(app='upload:app', reload=True)

调试步骤 #

1. 先添加错误详情捕获，查看具体错误代码（如AccessDenied）。
2. 检查传入的file_path格式，确保不以/开头且包含完整文件名（如subfolder/myfile.txt，而非subfolder/）。
3. 验证AWS凭证的权限范围，确认可写入指定的对象键路径。

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