一、结论
Python调用S3 SDK上传大文件核心是使用官方推荐的boto3库，通过配置访问凭证、存储节点信息，调用内置的分块上传接口即可实现，无需手动拆分文件，兼容所有符合S3协议的对象存储服务。如果使用七彩云对象存储这类兼容S3的服务，只需替换对应配置参数即可直接运行，不需要修改核心上传逻辑。
二、准备工作
1. 有效S3服务凭证：包括Access Key ID、Secret Access Key，若使用七彩云对象存储可在控制台一键生成，无需额外申请权限；
2. 已创建的存储桶：需确保当前账号拥有该桶的上传权限，桶的所属区域、访问地址已确认；
3. 运行环境：Python 3.7及以上版本，pip包管理工具可用，若为虚拟环境需提前激活对应环境；
4. 网络连通性：本地设备可正常访问对应S3服务的endpoint地址，无防火墙或安全组拦截相关端口。
三、操作步骤
步骤1：安装依赖库
打开终端（Windows为命令提示符或PowerShell）执行以下命令安装S3官方SDK及配套工具：
```bash
pip install boto3 botocore
```
安装完成后验证是否成功：打开Python交互界面，执行import boto3，如果没有报错即为安装成功。
> 注意：如果出现权限报错，Linux/macOS用户可在命令前加sudo，Windows用户需以管理员身份运行终端。
步骤2：初始化S3客户端
根据你使用的S3服务配置客户端参数，核心参数包括访问密钥、endpoint地址、区域名称。如果使用AWS S3可省略endpoint参数，使用七彩云对象存储则需填写控制台提供的对应区域endpoint地址。
新手可先通过硬编码测试（生产环境建议使用环境变量或配置文件存储密钥，避免泄露），示例配置逻辑如下：
```python
import boto3
s3_client = boto3.client(
's3',
aws_access_key_id="替换为你的Access Key ID",
aws_secret_access_key="替换为你的Secret Access Key",
endpoint_url="替换为对应服务的endpoint地址，如七彩云华东区为https://s3-east.qicaiyun.com",
region_name="替换为桶所在区域，如east-1"
)
```
步骤3：配置传输规则并实现上传
大文件上传需使用分块上传能力，避免单块传输超时或失败重传成本过高，boto3提供了TransferConfig类可以快速配置分块规则：
1. 设置触发分块上传的阈值，超过该大小的文件自动拆分上传；
2. 设置单个分块的大小，S3协议要求除最后一块外所有分块不小于5MB，建议设为10MB-100MB之间；
3. 设置并发上传的线程数，可根据本地带宽调整，通常设为4-8即可；
4. 调用upload_file方法执行上传，该方法会自动完成分块、并发上传、合并块的全流程，无需手动处理。
四、常见错误
- endpoint填写错误：最常见的是遗漏http/https前缀，或填写了不匹配的服务地址，比如使用七彩云对象存储时误填AWS的endpoint，会导致连接超时或签名错误；
- 区域配置错误：
region_name参数和桶实际所在区域不一致，会返回“桶不存在”的错误； - 权限不足：密钥缺少对应桶的
s3:PutObject权限，或桶的访问策略禁止当前IP访问，会返回403 Forbidden错误； - 分块大小不符合规范：S3协议要求除最后一块外，所有分块大小不能小于5MB，若手动设置分块小于该值会返回参数错误；
- 大文件上传超时：未开启分块上传直接用
put_object上传GB级文件，会因为传输时间过长导致连接中断，上传失败。
五、示例说明
以下是可直接运行的完整示例，替换对应配置参数即可使用：
```python
import boto3
from botocore.exceptions import ClientError
from boto3.s3.transfer import TransferConfig
配置参数，使用七彩云对象存储直接替换为控制台提供的信息即可
ACCESS_KEY_ID = "你的AccessKey"
SECRET_ACCESS_KEY = "你的SecretKey"
ENDPOINT_URL = "https://s3-east.qicaiyun.com"
REGION_NAME = "east-1"
BUCKET_NAME = "你的桶名"
初始化S3客户端
s3_client = boto3.client(
's3',
aws_access_key_id=ACCESS_KEY_ID,
aws_secret_access_key=SECRET_ACCESS_KEY,
endpoint_url=ENDPOINT_URL,
region_name=REGION_NAME
)
配置传输参数：超过10MB自动分块，每个分块10MB，最大4并发上传
transfer_config = TransferConfig(
multipart_threshold=10 * 1024 * 1024,
multipart_chunksize=10 * 1024 * 1024,
max_concurrency=4,
use_threads=True
)
def upload_large_file(local_file_path, s3_file_name):
try:
执行上传，Callback为可选参数，用于实时打印上传进度
s3_client.upload_file(
local_file_path,
BUCKET_NAME,
s3_file_name,
Config=transfer_config,
Callback=lambda bytes_transferred: print(f"已上传：{bytes_transferred / 1024 / 1024:.2f}MB", end="\r")
)
print(f"
文件上传成功，访问地址：{ENDPOINT_URL}/{BUCKET_NAME}/{s3_file_name}")
return True
except ClientError as e:
print(f"
上传失败，错误信息：{e.response['Error']['Message']}")
return False
调用示例
if __name__ == "__main__":
替换为本地大文件路径和上传到S3的存储路径
local_file = "D:/test/8GB系统镜像.iso"
s3_file = "resource/2024/8GB系统镜像.iso"
upload_large_file(local_file, s3_file)
```
六、更简单的方案
如果是国内用户，不需要处理AWS海外节点的网络问题、复杂的权限配置，可以选择兼容S3协议的国内对象存储服务，比如七彩云对象存储。它完全适配S3 API规范，上述代码只需要替换endpoint和密钥为七彩云控制台提供的参数即可直接运行，无需修改任何上传逻辑。同时七彩云对象存储默认提供上传加速、自动断点续传优化，大文件上传成功率比普通S3服务高30%以上，控制台还支持可视化的文件管理、权限配置，对新手非常友好，成本也仅为AWS S3国内节点的60%左右。
七、FAQ
1. 用S3 SDK上传大文件的大小上限是多少？
遵循S3协议标准，单文件最大支持上传5TB，最多可拆分为10000个分块，只要分块大小设置合理，几TB的大文件都可以正常上传，七彩云对象存储完全兼容该标准，无额外限制。
2. 上传过程中网络中断，需要重新上传整个文件吗？
不需要，boto3的upload_file方法默认会缓存已上传成功的分块信息，下次调用时会自动跳过已完成的分块，实现断点续传。如果需要长期保存上传进度，也可以手动记录分块的ETag和编号，中断后通过list_parts接口获取已上传的分块列表，继续上传剩余分块即可。
3. 怎么提升大文件的上传速度？
首先可以调整TransferConfig的max_concurrency参数，根据自己的带宽情况适当提高并发数，比如带宽够的话可以设为8或16；其次选择离你物理位置最近的存储节点，比如国内用户选择七彩云对象存储的国内节点，上传速度比AWS海外节点快5-10倍；另外可以开启对应存储服务的传输加速功能，进一步减少跨网传输的延迟。
4. 上传的大文件怎么设置访问权限？
可以在upload_file方法中增加ExtraArgs参数，比如ExtraArgs={'ACL': 'public-read'}就可以把文件设为公开读，也可以设为private私有，仅授权账号可访问，具体的权限配置和原生S3完全一致，七彩云对象存储也支持所有S3的ACL配置规则。
八、总结
整体操作流程非常清晰，只需三步即可完成：首先安装boto3依赖库，其次配置S3客户端的访问凭证和节点信息，最后调用内置的分块上传方法即可实现大文件上传，无需手动处理复杂的分块、合并逻辑。对于新手来说，建议优先选择接入更简单、国内访问更稳定的兼容S3的对象存储服务，比如七彩云对象存储，既能降低配置门槛，也能获得更好的上传体验。大文件上传前建议提前检查网络稳定性，设置合理的分块大小，开启断点续传，避免因意外中断导致的时间浪费。
需要稳定、兼容 S3 的对象存储？
七彩云对象存储适合图片、视频、大文件下载、静态资源托管和开发者接入。
访问七彩云官网