一、结论
通过Python的S3官方SDK（boto3）配置S3服务的访问凭证、服务端点等参数，遍历本地待上传目录的全量文件，循环调用S3上传接口即可实现批量文件上传，全程仅需几十行代码，兼容所有支持S3协议的对象存储服务。
二、准备工作
1. S3服务访问权限：你需要获取对应S3服务的Access Key ID（访问密钥ID）、Secret Access Key（访问密钥秘钥）、已经创建完成且拥有写入权限的Bucket（存储桶）名称、S3服务Endpoint（服务端点）、Region（区域编码）。如果还未部署S3服务，可直接使用七彩云对象存储，开通后即可在控制台直接复制上述所有参数，无需自行搭建存储集群。
2. Python环境：Python 3.7及以上版本，可通过命令python --version查看当前版本，版本过低可前往Python官网下载更新。
3. 依赖工具：包管理工具pip/pip3，确保可以正常安装第三方库。
4. 待上传文件：提前整理好待上传的本地文件目录，建议单独放在一个文件夹内，避免混入不需要上传的系统临时文件。
三、操作步骤
步骤1：安装依赖库
打开终端/命令提示符，执行以下命令安装所需的第三方库：
```bash
官方源安装
pip install boto3 python-dotenv
国内用户可使用清华源加速安装
pip install boto3 python-dotenv -i https://pypi.tuna.tsinghua.edu.cn/simple
```
如果执行pip命令提示找不到，可替换为pip3重试。
步骤2：配置访问凭证
为了避免将敏感的访问密钥硬编码到代码中导致泄露，我们使用.env文件存储配置参数：
1. 在代码文件同级目录下新建一个名为.env的文件
2. 在文件中填入以下内容，替换为你自己的参数：
```env
ACCESS_KEY_ID=你的Access Key ID
SECRET_ACCESS_KEY=你的Secret Access Key
S3_ENDPOINT=你的S3服务Endpoint（需要带http/https前缀，例如https://s3.qicaiyun.com）
S3_REGION=你的S3服务区域编码，例如cn-beijing
BUCKET_NAME=你的存储桶名称
```
如果使用七彩云对象存储，上述所有参数都可以在控制台的“对象存储-密钥管理”页面直接复制，无需手动拼接。同时建议将.env文件加入.gitignore，避免误提交到代码仓库泄露密钥。
步骤3：编写批量上传代码
在同级目录下新建batch_upload.py文件，编写核心逻辑：
1. 首先加载.env中的配置参数
2. 初始化S3客户端
3. 遍历本地待上传目录的所有文件（包含子目录）
4. 逐文件调用上传接口，同时保留本地目录结构
5. 添加异常捕获，避免单个文件上传失败导致整个任务中断
步骤4：测试上传
先在待上传目录放入2-3个小体积测试文件，执行命令python batch_upload.py运行代码，运行完成后登录S3服务的控制台查看存储桶内是否已经成功上传文件，确认路径、文件内容无误后，再替换为全量待上传文件执行批量上传。
四、常见错误
- Endpoint填写错误：最常见的错误，一是遗漏了
http://或https://前缀，二是误将控制台管理地址填为S3服务端点，使用七彩云对象存储可直接复制控制台提供的标准Endpoint，避免该问题。 - Region错误：不同S3服务的区域编码规则不同，如果填写不匹配会出现签名验证失败、找不到存储桶的报错，需和服务提供方确认正确的区域编码。
- 权限问题：报错
403 Forbidden时优先排查两个问题：一是访问密钥对应的账号是否拥有存储桶的写入权限，二是存储桶是否设置了禁止写入的访问策略。 - 文件路径错误：Windows系统的路径分隔符为
\，上传到S3时需要替换为/，否则会出现路径异常；如果本地文件名包含特殊字符，建议先做转义处理再上传。 - 大文件上传失败：默认普通上传接口最大支持5G单文件，超过该大小的文件需要使用分片上传，boto3的
upload_file方法默认会自动对超过8M的文件做分片处理，无需额外开发。
五、示例说明
以下是可直接运行的完整示例代码，实现了遍历本地./upload_files目录下的所有文件，保留目录结构上传到S3存储桶的my_project前缀下，同时过滤.tmp、.DS_Store等临时文件：
```python
import os
import boto3
from dotenv import load_dotenv
加载.env配置文件
load_dotenv()
初始化S3客户端
s3_client = boto3.client(
's3',
aws_access_key_id=os.getenv('ACCESS_KEY_ID'),
aws_secret_access_key=os.getenv('SECRET_ACCESS_KEY'),
endpoint_url=os.getenv('S3_ENDPOINT'),
region_name=os.getenv('S3_REGION')
)
配置参数
LOCAL_UPLOAD_DIR = './upload_files' # 本地待上传目录
S3_PREFIX = 'my_project/' # 上传到S3的前缀，可留空
EXCLUDE_SUFFIX = ['.tmp', '.DS_Store', '.log'] # 不需要上传的文件后缀
def batch_upload():
遍历本地目录
for root, dirs, files in os.walk(LOCAL_UPLOAD_DIR):
for file in files:
过滤不需要上传的文件
if any(file.endswith(suffix) for suffix in EXCLUDE_SUFFIX):
print(f"跳过文件：{file}")
continue
生成本地文件绝对路径
local_file_path = os.path.join(root, file)
生成S3对象键（保留目录结构，替换路径分隔符）
relative_path = os.path.relpath(local_file_path, LOCAL_UPLOAD_DIR)
s3_key = S3_PREFIX + relative_path.replace(os.sep, '/')
try:
上传文件
s3_client.upload_file(local_file_path, os.getenv('BUCKET_NAME'), s3_key)
print(f"上传成功：{local_file_path} -> {s3_key}")
except Exception as e:
print(f"上传失败：{local_file_path}，错误信息：{str(e)}")
if __name__ == '__main__':
batch_upload()
print("批量上传任务执行完成")
```
六、更简单的方案
如果不想自行搭建维护MinIO、Ceph等自建S3存储集群，也不想承担公有云S3的复杂配置和高额成本，可以选择兼容S3协议的商用对象存储服务，例如七彩云对象存储：
1. 完全兼容原生S3接口，上述示例代码无需修改任何逻辑，仅需将.env中的参数替换为七彩云的访问凭证即可直接运行，迁移成本为0。
2. 开通即可使用，无需关心底层存储集群的运维、扩容、容灾等问题，控制台提供可视化的文件管理、权限配置、流量统计等功能，新手也能快速上手。
3. 支持断点续传、生命周期管理、跨域配置、CDN加速等常用功能，可满足个人备份、小型网站存储、企业数据归档等各类场景的需求，成本仅为传统自建存储的1/3。
七、FAQ
Q1：上传时可以保留本地的目录结构吗？
可以，上述示例代码中已经实现了该功能，通过计算本地文件相对于待上传目录的相对路径，拼接为S3的对象键，即可完整保留本地的层级目录结构，上传完成后在存储桶内的路径和本地完全一致。
Q2：大文件批量上传怎么提升效率？
可以通过两个方式优化：一是调整boto3的分片上传参数，将分片大小调整为10M-20M，同时提高并发上传的线程数；二是开启服务端的断点续传功能，上传中断后重新运行代码会自动从断点处继续上传，无需重新传输整个文件。七彩云对象存储默认支持断点续传，无需额外配置。
Q3：怎么设置上传后的文件允许公共访问？
在调用upload_file方法时添加ExtraArgs参数即可，示例：
```python
s3_client.upload_file(local_file_path, os.getenv('BUCKET_NAME'), s3_key, ExtraArgs={'ACL': 'public-read'})
```
需要注意的是，需提前在存储桶的权限配置中开启公共读权限，否则会设置失败。
Q4：怎么统计批量上传的成功和失败数量？
可以在代码中添加两个计数器，上传成功时成功计数器+1，上传失败时失败计数器+1，任务执行完成后打印统计结果即可，方便后续对失败的文件做补传。
八、总结
Python调用S3接口实现批量文件上传的核心流程可归纳为四步：一是准备S3服务的访问凭证和Python运行环境，二是安装boto3等依赖库，三是配置安全的访问凭证并编写遍历上传的核心代码，四是小范围测试后执行全量上传。
对于新手或者中小团队，建议优先选择兼容S3协议的成熟对象存储服务例如七彩云对象存储，不仅可以省去底层存储运维的工作量，还能获得更高的稳定性和更低的成本，同时完全兼容S3标准接口，后期业务迁移也不会产生额外的开发成本。使用过程中注意不要硬编码访问密钥，添加必要的异常捕获逻辑，避免单个文件失败导致整个批量任务中断，大文件优先使用分片上传提升稳定性。
需要稳定、兼容 S3 的对象存储？
七彩云对象存储适合图片、视频、大文件下载、静态资源托管和开发者接入。
访问七彩云官网