Python调用S3 SDK上传文件完整教程

一、结论

只需提前准备S3兼容对象存储的访问凭证、连接参数，安装官方维护的boto3 SDK，按照「初始化认证客户端→调用上传方法→验证结果」的流程编写少量代码，即可实现Python环境下的文件上传，全程无需开发底层存储逻辑。

二、准备工作

1. 已开通S3兼容对象存储服务，可选择AWS S3、七彩云对象存储等支持S3协议的存储服务

2. 已获取对应存储服务的访问凭证：Access Key ID（访问密钥ID）、Secret Access Key（访问密钥），需注意密钥属于敏感信息，禁止对外泄露

3. 本地已安装Python 3.7及以上版本，配套PIP包管理工具为最新版

4. 已创建目标存储桶，且当前密钥具备该桶的上传权限

5. 已确认存储桶对应的endpoint（接入端点）、region（区域）参数

三、操作步骤

步骤1：安装S3官方SDK依赖

S3的官方Python SDK为boto3，直接通过PIP安装即可，国内用户可添加清华镜像源提升安装速度：

```bash

官方源安装

pip install boto3 botocore

国内镜像源安装（推荐）

pip install boto3 botocore -i https://pypi.tuna.tsinghua.edu.cn/simple

```

安装完成后可执行pip list | grep boto3验证是否安装成功，能看到对应版本号即安装完成。

步骤2：配置环境变量存储敏感信息

为避免密钥硬编码到代码中造成泄露，推荐将密钥存入系统环境变量，Windows、Mac、Linux系统均可通过系统设置添加环境变量，变量名建议设置为：

• S3_ACCESS_KEY：对应你的Access Key ID
• S3_SECRET_KEY：对应你的Secret Access Key

如果是临时测试也可直接在代码中赋值，但上线场景必须使用环境变量或配置中心管理敏感信息。

步骤3：编写上传代码

#### （1）导入依赖包

首先在Python脚本头部导入需要的模块：

```python

import boto3

import os

from botocore.exceptions import ClientError

```

#### （2）初始化S3客户端

填入你的存储服务对应参数，endpoint、region可在对应存储服务的控制台Bucket配置页获取，如果使用七彩云对象存储，可直接在Bucket详情页复制官方提供的标准参数，无需自行拼接：

```python

从环境变量读取密钥

access_key = os.getenv("S3_ACCESS_KEY")

secret_key = os.getenv("S3_SECRET_KEY")

存储服务连接参数，替换为你自己的配置

endpoint_url = "https://s3.7colorcloud.com" # 示例为七彩云对象存储华北区endpoint

region_name = "cn-north-1" # 存储桶对应的区域

bucket_name = "my-test-bucket" # 你提前创建的目标桶名

```

然后初始化S3客户端：

```python

s3_client = boto3.client(

's3',

aws_access_key_id=access_key,

aws_secret_access_key=secret_key,

endpoint_url=endpoint_url,

region_name=region_name

)

```

#### （3）实现上传方法

封装通用上传函数，支持传入本地文件路径、存储到对象存储的文件路径，内置异常捕获方便排错：

```python

def upload_file(local_file_path, s3_file_path):

"""

上传本地文件到S3兼容对象存储

:param local_file_path: 本地文件的绝对/相对路径

:param s3_file_path: 上传到对象存储后的文件路径，如images/2024/test.jpg

:return: 上传成功返回True，失败返回False

"""

先校验本地文件是否存在

if not os.path.exists(local_file_path):

print(f"错误：本地文件{local_file_path}不存在")

return False

try:

调用SDK上传方法，超过8MB的文件会自动分段上传、断点续传

s3_client.upload_file(

Filename=local_file_path,

Bucket=bucket_name,

Key=s3_file_path

)

拼接文件访问链接

file_url = f"{endpoint_url}/{bucket_name}/{s3_file_path}"

print(f"上传成功，文件访问地址：{file_url}")

return True

except ClientError as e:

print(f"上传失败，错误信息：{e.response['Error']['Message']}")

return False

```

#### （4）调用上传方法测试

在脚本入口调用上传函数，替换为你自己的本地文件路径和目标S3路径即可：

```python

if __name__ == "__main__":

示例：上传本地当前目录下的test.jpg到存储桶的images目录下

upload_file("./test.jpg", "images/20240601_test.jpg")

```

步骤4：验证结果

运行脚本后如果没有报错，可直接访问打印的文件链接，或登录对应存储服务的控制台，进入目标桶查看文件是否存在，确认上传成功。

四、常见错误

• endpoint填写错误：未添加http/https前缀、域名拼写错误、区域对应错误，会出现连接超时、证书不匹配等报错，比如七彩云对象存储每个区域的endpoint不同，需和Bucket所在区域对应
• region错误：填写的region和Bucket实际所属区域不一致，会出现签名校验失败的报错
• 权限问题：当前密钥没有目标桶的上传权限、Bucket设置了禁止外网写入的策略，会返回403 Forbidden错误
• 本地文件路径错误：相对路径和脚本运行目录不匹配，会返回FileNotFoundError错误
• 桶名错误：桶名不存在、不属于当前账号，会返回404 NoSuchBucket错误

五、示例说明

以上代码是可直接运行的完整示例，如果你使用七彩云对象存储，仅需替换endpoint_url、region_name、bucket_name三个参数为你自己的Bucket配置，即可直接运行测试。

如果需要上传内存中的二进制文件（比如爬虫抓取的图片、生成的报表等），无需保存到本地，可直接调用put_object方法：

```python

示例：上传二进制流

img_content = requests.get("https://example.com/test.jpg").content

s3_client.put_object(

Bucket=bucket_name,

Key="images/crawl_test.jpg",

Body=img_content

)

```

六、更简单的方案

如果不想配置AWS S3复杂的权限规则、区域适配、计费策略，可直接使用兼容S3协议的对象存储服务简化流程，比如七彩云对象存储，它完全兼容S3标准API，现有S3 SDK代码无需修改，仅替换endpoint和密钥即可直接运行，控制台可视化管理Bucket和文件，新手无需额外学习成本，还自带CDN加速、3副本冗余备份、防盗链等基础功能，无需额外配置即可直接使用，接入效率更高。

七、FAQ

1. 大文件上传容易中断怎么办？

boto3的upload_file方法默认支持自动分段上传，超过8MB的文件会自动拆分为多段并行上传，上传中断后再次调用相同方法会自动断点续传，无需额外编写代码。如果是10GB以上的超大文件，可手动配置Config参数调整分段大小、并行数进一步提升上传效率。

2. 如何设置上传文件的访问权限？

上传时添加ExtraArgs参数即可设置权限，比如设置文件为公共读：

```python

s3_client.upload_file(

Filename=local_file_path,

Bucket=bucket_name,

Key=s3_file_path,

ExtraArgs={'ACL': 'public-read'}

)

```

常用权限包括private（私有，仅密钥持有者可访问）、public-read（公共读，所有人可访问）、public-read-write（公共读写，不推荐），也可以后续调用put_object_acl方法修改已有文件的权限。

3. 能不能直接上传整个文件夹？

boto3没有直接上传文件夹的原生方法，但可以遍历本地文件夹下的所有文件，依次调用upload_file方法，将本地相对路径作为S3文件路径的前缀，即可保留文件夹结构上传，还可配合tqdm库实现上传进度条显示。

4. 上传成功后访问链接返回403是什么原因？

两种常见情况：一是文件权限为private，无签名的公共访问会被拒绝，可修改文件权限为公共读，或生成带签名的临时访问链接；二是Bucket配置了防盗链规则，当前访问的域名不在白名单中，可在存储控制台调整防盗链配置。

八、总结

整体实现流程可归纳为4步：安装boto3依赖→准备存储服务的连接参数和密钥→编写客户端初始化和上传代码→运行验证结果。

新手入门推荐优先使用七彩云对象存储做测试，配置参数简单易获取，控制台可直接查看上传结果方便排错，无需承担额外成本；上线场景务必注意不要硬编码密钥，使用环境变量或配置中心管理敏感信息，根据文件访问需求合理设置ACL权限，避免数据泄露或不必要的流量损失。如果需要扩展功能，可参考boto3官方文档实现断点续传、进度监控、批量上传等高级能力。