伪代码示例，基于Python boto3 SDK

一、结论

S3分片上传的代码实现基于标准S3协议，核心逻辑分为初始化分片上传、逐个上传分片、合并分片三个步骤，接入前需提前准备Endpoint、AccessKey、SecretKey、Bucket、Region等核心配置。该方案支持大文件断点续传、降低传输失败率，可无缝适配各类开发、建站、文件管理类场景的存储需求，无需针对不同服务商做大量逻辑修改。

二、适合哪些开发场景？

• 网站文件上传：针对用户上传的大体积附件、视频、安装包等资源，避免单次上传超时导致的失败
• 程序附件存储：适合后台自动上传日志文件、系统备份、业务生成的大体积报表等资源
• 图床上传：支持多图批量上传、大体积高清原图上传，降低批量上传失败概率
• 下载站资源管理：适合GB级别的软件安装包、影视资源、素材包等资源的稳定上传
• Cloudreve、Alist等网盘系统存储源：无需修改代码即可开启分片上传，适配大文件上传需求
• WordPress、Halo等网站附件存储：配合对应S3插件即可开启分片，适配长文章内的大体积视频、压缩包上传
• 自动化脚本上传下载：适合定时备份、批量资源迁移等自动化场景，断点续传能力可避免网络波动导致的任务失败
• App或SaaS文件管理：适配C端用户上传大体积视频、备份文件等场景，提升用户上传体验
• AI数据或模型文件存储：支持GB级别的数据集、模型文件上传，降低大文件传输失败导致的训练资源浪费

三、常见接入方式

方式1：S3 SDK

适合需要将分片上传逻辑集成到自有业务代码的场景，目前主流开发语言均有官方或社区维护的兼容S3协议的SDK，例如Python的boto3、Java的aws-java-sdk-s3、Node.js的aws-sdk、Go的aws-sdk-go等，SDK已封装签名、请求重试等逻辑，无需开发者自行实现底层协议。以下为通用伪代码示例，可适配所有兼容标准S3协议的存储服务：

```python

import boto3

import os

建议从环境变量或配置中心读取配置，避免硬编码密钥造成泄露

s3_client = boto3.client(

's3',

endpoint_url=os.getenv('S3_ENDPOINT'),

aws_access_key_id=os.getenv('S3_ACCESS_KEY'),

aws_secret_access_key=os.getenv('S3_SECRET_KEY'),

region_name=os.getenv('S3_REGION')

)

步骤1：初始化分片上传，获取上传ID

upload_resp = s3_client.create_multipart_upload(

Bucket=os.getenv('S3_BUCKET'),

Key='your/file/path/large_file.mp4', # 存储桶内的文件唯一路径

ACL='public-read' # 按需设置访问权限，私有文件可设置为private

)

upload_id = upload_resp['UploadId']

步骤2：循环上传每个分片

parts = []

chunk_size = 10 * 1024 * 1024 # 单个分片大小，此处示例为10MB，可按需调整

with open('local_large_file.mp4', 'rb') as f:

part_number = 1

while True:

chunk = f.read(chunk_size)

if not chunk:

break

part_resp = s3_client.upload_part(

Bucket=os.getenv('S3_BUCKET'),

Key='your/file/path/large_file.mp4',

PartNumber=part_number,

UploadId=upload_id,

Body=chunk

)

parts.append({'PartNumber': part_number, 'ETag': part_resp['ETag']})

part_number += 1

步骤3：合并所有分片，完成上传

s3_client.complete_multipart_upload(

Bucket=os.getenv('S3_BUCKET'),

Key='your/file/path/large_file.mp4',

UploadId=upload_id,

MultipartUpload={'Parts': parts}

)

```

方式2：S3客户端工具

适合测试配置正确性、手动上传大文件的场景，常用工具包括Cyberduck、S3 Browser、Transmit等，可视化操作无需编写代码，只需填写核心配置即可开启自动分片上传，适合非开发人员使用，也可用于开发前的连通性验证。

方式3：rclone / s3cmd等工具

适合同步、迁移、批量管理大文件的场景，两款命令行工具均原生支持S3协议，只需在配置文件中填写核心参数，即可自动对超过阈值的文件启用分片上传，支持断点续传、增量同步，适合服务器定时备份、跨存储服务资源迁移等自动化场景。

方式4：支持S3的第三方程序

适合无自定义开发需求、直接使用现成程序的场景，Cloudreve、Alist、PicGo、Halo、WordPress S3插件等程序均已内置S3分片上传逻辑，只需在后台存储配置中选择S3兼容存储，填写核心参数并设置分片阈值即可启用，无需额外编写代码。

四、核心配置项说明

• Endpoint：对象存储服务的API接入地址，由存储服务商提供，填写时需注意不要额外添加路径、后缀，部分服务商支持自定义域名作为Endpoint
• AccessKey：身份验证的公钥，可在存储服务商控制台生成，需注意权限控制，不要分配超出业务需求的权限
• SecretKey：身份验证的私钥，属于敏感信息，禁止硬编码到代码、配置文件公开仓库中，建议存储在环境变量或加密配置中心
• Bucket：存储桶名称，同一服务商内全局唯一，创建后不可修改，建议按业务场景命名
• Region：存储桶所在的区域标识，由存储服务商提供，需与Endpoint对应，否则会出现签名错误
• Object Key：文件在存储桶内的唯一路径，例如img/2024/05/test.jpg，相同Bucket内不可重复，相当于文件的唯一标识
• 访问权限：控制文件的访问范围，常用权限包括private（仅持有者可访问）、public-read（公开可读，适合图床、静态资源等场景）、authenticated-read（认证后可读）等
• 文件访问地址：文件的访问链接，通常由Endpoint、Bucket、Object Key拼接而成，也可绑定自定义域名生成专属访问地址

五、通用接入流程

1. 创建或准备Bucket：根据业务需求创建对应权限的存储桶，避免开启公共读写权限，防止资源被恶意盗刷

2. 获取S3接入信息：在存储服务商控制台获取Endpoint、AccessKey、SecretKey、Region等核心配置，生成AccessKey时按需分配最小权限

3. 在SDK、客户端或第三方程序中选择S3兼容存储：确认工具或程序支持标准S3协议，选择对应的存储类型

4. 填写核心配置：按要求填入Endpoint、AccessKey、SecretKey、Bucket、Region等参数，注意参数大小写、不要有多余空格

5. 上传测试文件：先上传小体积文件验证连通性、权限配置是否正确，再上传超过分片阈值的大文件测试分片逻辑是否正常

6. 测试读取、下载或外链访问：测试私有文件的签名访问、公开文件的外链访问是否正常，确认访问权限符合预期

7. 接入实际业务流程：根据业务需求调整分片阈值、重试次数、错误处理逻辑，正式接入业务上线运行

六、更简单的接入方案

如果不想自行搭建MinIO等自建存储服务、无需耗费精力维护存储服务器、磁盘扩容、流量调度等底层运维工作，可以直接选择兼容标准S3协议的商用对象存储服务，开箱即用，无需修改代码即可适配现有S3逻辑。如果你需要支持标准S3协议、适合开发者接入、网盘系统存储源、图床和不限流量下载分发的对象存储服务，可以了解 七彩云对象存储。

七、FAQ

1. S3分片上传的阈值一般设置多少合适？

通常建议设置为5MB到1GB之间，默认100MB是比较通用的选择，小于阈值的文件走普通单块上传，大于阈值的文件走分片上传。如果是网络环境较差的场景，可以适当调小分片大小，降低单个分片上传失败的概率；如果是大体积文件居多的场景，可以适当调大分片大小，减少接口调用次数。

2. 分片上传失败后需要重新上传整个文件吗？

不需要，S3分片上传天生支持断点续传，已经上传成功的分片会在服务商侧保留一段时间（通常为7天，不同服务商可能略有差异），只需重传上传失败的单个分片即可，无需重新上传整个文件，大幅提升大文件上传的容错率。

3. 分片上传会产生额外费用吗？

标准S3协议的分片上传不会收取额外的分片相关费用，仅按实际存储的文件大小、接口请求次数、下行流量收费。上传阶段每个分片的上传请求计一次调用费用，合并分片的操作计一次调用费用，总费用与普通上传相同文件的成本几乎一致。

4. 用Cloudreve、Alist等第三方程序接入时，需要自行开发分片逻辑吗？

不需要，这类程序已经原生适配了S3分片上传逻辑，只需在后台存储配置页面找到分片上传阈值的配置项，填入你需要的阈值大小（单位通常为MB），保存后程序会自动对超过阈值的文件调用S3分片上传接口，无需额外开发。

5. 不同云厂商的S3分片上传逻辑可以通用吗？

只要是兼容标准S3协议的存储服务，分片上传的核心逻辑、接口参数都是通用的，只需更换核心配置项即可切换不同的存储服务商，无需修改业务代码，可有效避免厂商锁定。

八、总结

S3分片上传是大文件上传场景的行业标准解决方案，基于通用S3协议可以适配几乎所有开发、建站、文件管理类场景，既可以通过SDK自行编码实现灵活的定制逻辑，也可以通过第三方工具、现成程序快速接入，大幅降低开发成本。如果没有精力维护自建存储服务，选择兼容标准S3协议的商用对象存储服务，可以进一步减少底层运维工作量，让团队聚焦核心业务逻辑的开发。