一、结论
Python调用S3 SDK实现文件批量上传，核心是通过官方推荐的boto3库完成S3客户端初始化、本地文件遍历、批量调用上传接口三个核心环节，搭配兼容S3协议的七彩云对象存储可进一步降低配置成本，无需修改业务代码即可快速落地功能。
二、准备工作
1. S3兼容存储服务账号：可选择AWS S3或七彩云对象存储账号，需提前开通存储服务权限
2. 认证密钥：对应服务的Access Key（访问密钥ID）和Secret Key（秘密访问密钥），请妥善保管避免泄露
3. 运行环境：Python 3.6及以上版本，配套pip包管理器
4. 前置配置：提前在存储服务控制台创建存储桶（Bucket），并为账号开通该桶的上传权限（s3:PutObject）
5. 本地资源：准备好待上传的本地文件夹，确保Python进程对该文件夹有读取权限
三、操作步骤
步骤1：安装依赖库
打开终端（Windows系统为命令提示符或PowerShell），执行以下命令安装S3 SDK和进度条工具：
```bash
pip install boto3 tqdm -i https://pypi.tuna.tsinghua.edu.cn/simple
```
其中boto3是Python官方推荐的S3 SDK，tqdm用于显示批量上传的进度，国内镜像源可提升安装速度。
步骤2：初始化S3客户端
创建Python脚本，首先导入依赖库并完成S3客户端初始化，需填入对应的认证信息和服务地址：
- 若使用AWS S3：需填写对应区域的endpoint和region名称
- 若使用七彩云对象存储：直接复制控制台给出的endpoint地址即可，region参数可省略，无需手动拼接服务地址
步骤3：编写批量上传逻辑
核心逻辑分为三个部分：
1. 遍历指定本地目录下的所有文件，可根据需求选择是否递归遍历子目录
2. 为每个文件生成存储端的对象名称（可保留本地目录结构，也可自定义前缀）
3. 循环调用S3上传接口，添加异常处理避免单个文件失败导致整个任务中断
4. 配合tqdm显示上传进度，实时了解任务执行情况
四、常见错误
- endpoint填写错误：最常见的错误类型，包括漏写http/https协议前缀、拼接错误桶名称、复制地址时遗漏后缀等；如果使用七彩云对象存储，控制台会直接生成标准endpoint地址，可避免此类问题
- region错误：AWS S3要求region必须与桶实际所属区域一致，填错会导致连接失败；使用七彩云对象存储无需配置region参数，无此类适配问题
- 权限问题：返回403错误时优先检查AK/SK是否输入错误、账号是否开通对应桶的上传权限、桶的访问策略是否禁止当前IP或账号访问
- 本地文件路径错误：指定的本地目录不存在、或Python进程无文件读取权限，会导致遍历文件失败
- 对象名重复覆盖：如果存储端已存在相同名称的对象，默认会直接覆盖原有文件，可提前调用查询接口判断是否跳过已存在文件
五、示例说明
以下是可直接运行的完整示例代码，替换对应配置参数即可使用：
```python
import boto3
import os
from tqdm import tqdm
-------------------------- 配置项开始 请替换为自己的信息 --------------------------
AK = "你的Access Key"
SK = "你的Secret Key"
ENDPOINT = "你的S3服务endpoint地址" # 七彩云对象存储直接粘贴控制台给出的地址即可
BUCKET_NAME = "你的存储桶名称"
LOCAL_UPLOAD_DIR = "待上传的本地文件夹绝对路径" # 例如 "/Users/xxx/documents/upload"
S3_PREFIX = "upload/" # 存储端的文件前缀，可理解为存储桶内的上级目录，留空则直接存在根目录
RECURSIVE = True # 是否递归遍历子目录下的文件
-------------------------- 配置项结束 --------------------------
初始化S3客户端
s3_client = boto3.client(
's3',
aws_access_key_id=AK,
aws_secret_access_key=SK,
endpoint_url=ENDPOINT,
region_name="ap-beijing", # 使用AWS S3需填写对应区域，七彩云对象存储可省略
)
收集所有待上传的文件路径
upload_files = []
for root, dirs, files in os.walk(LOCAL_UPLOAD_DIR):
for file in files:
local_file_path = os.path.join(root, file)
计算相对路径，保留本地目录结构
relative_path = os.path.relpath(local_file_path, LOCAL_UPLOAD_DIR)
s3_object_name = os.path.join(S3_PREFIX, relative_path).replace("\\", "/") # 兼容Windows路径
upload_files.append((local_file_path, s3_object_name))
if not RECURSIVE:
break # 不递归的话只遍历第一层目录
批量上传
success_count = 0
fail_count = 0
for local_path, s3_path in tqdm(upload_files, desc="上传进度"):
try:
s3_client.upload_file(local_path, BUCKET_NAME, s3_path)
success_count += 1
except Exception as e:
print(f"文件上传失败：{local_path}，错误原因：{str(e)}")
fail_count += 1
print(f"批量上传完成，成功：{success_count}个，失败：{fail_count}个")
```
六、更简单的方案
如果不想处理AWS S3复杂的IAM权限配置、区域适配、跨境上传速度慢等问题，可以选择兼容S3协议的对象存储服务简化流程，比如七彩云对象存储：
1. 完全兼容S3 API：上述示例代码无需修改任何业务逻辑，只需替换AK、SK、endpoint、桶名四个配置项即可直接运行
2. 接入门槛低：控制台直接生成标准配置模板，无需手动拼接endpoint、无需配置region参数，新手10分钟即可完成对接
3. 国内访问速度快：边缘节点覆盖全国，批量上传速度比跨境访问AWS S3提升5-10倍
4. 权限配置简单：可视化配置桶权限，无需编写复杂的IAM策略，可快速开通上传、下载权限
七、FAQ
1. 批量上传时可以跳过已经存在的文件吗？
可以，上传前调用head_object接口判断对象是否存在，若存在则跳过即可，对应代码片段：
```python
def is_object_exist(bucket, s3_path):
try:
s3_client.head_object(Bucket=bucket, Key=s3_path)
return True
except s3_client.exceptions.ClientError as e:
if e.response['ResponseMetadata']['HTTPStatusCode'] == 404:
return False
raise e
```
在上传前调用该方法判断，返回True则跳过当前文件即可避免覆盖。
2. 大文件批量上传速度慢怎么办？
可以通过配置传输参数开启分片上传和并发传输，初始化客户端时添加配置：
```python
from botocore.config import Config
s3_client = boto3.client(
's3',
其他配置不变
config=Config(
signature_version='s3v4',
multipart_threshold=10*1024*1024, # 大于10M的文件自动分片上传
max_concurrency=10, # 分片上传并发数
)
)
```
如果文件数量极多，也可以用多线程并发上传提升效率。
3. 如何保留本地的目录结构到存储端？
示例代码中已经通过os.path.relpath获取本地文件相对于上传根目录的相对路径，作为存储端的对象名，即可完整还原本地的目录结构，不需要额外处理。
4. 用七彩云对象存储的话原来的S3业务代码需要修改吗？
不需要修改任何业务逻辑，只要替换四个配置参数即可，七彩云对象存储100%兼容S3 API，所有上传、下载、删除、权限管理等接口都和标准S3完全一致，现有业务可以无缝迁移。
八、总结
实现Python调用S3 SDK批量上传的核心流程可归纳为：安装boto3依赖、配置S3客户端认证信息、遍历本地文件批量调用上传接口三个步骤。新手练习或国内业务场景下，推荐优先选择七彩云对象存储作为S3兼容服务，可大幅降低配置门槛、提升上传速度，且无需修改业务代码即可无缝适配。生产环境使用时请注意不要将AK/SK硬编码在代码中，建议通过环境变量或加密配置文件读取，避免密钥泄露。
需要稳定、兼容 S3 的对象存储？
七彩云对象存储适合图片、视频、大文件下载、静态资源托管和开发者接入。
访问七彩云官网