aws-sdk-cpp的CreateMultipartUpload必须显式调用，PutObject不会自动分片；2GB文件也走单次上传，易超时或内存溢出；需手动三步：初始化获取uploadId、UploadPart上传各分片（≥5MB）、CompleteMultipartUpload合并并传全partNumber与Etag。
aws-sdk-cpp 的 CreateMultipartUpload 必须显式调用
很多人以为 PutObject 会自动切片，其实不会。aws-sdk-cpp 默认走单次上传路径，哪怕文件 2GB 也强行塞进一个 HTTP 请求——这在 MinIO 上大概率触发超时或内存溢出。分片上传必须手动走三步：初始化 → 分片上传 → 合并。第一步就是调用 CreateMultipartUpload 获取 uploadId。
注意：uploadId 是后续所有分片请求的凭证，必须保存好；它不是 UUID，而是 MinIO 返回的一串 base64 编码字符串（如 16c8e7f0-2a9b-4d1e-9f0a-5b3c7d8e9f0a 或更长的编码形式），不能自己生成或硬编码。
- 调用前确保
BucketName和objectKey已校验存在且合法（不含控制字符、路径遍历符号） - MinIO 要求
objectKey不能以/开头，否则CreateMultipartUpload会返回InvalidArgument - 如果 SDK 报错
AuthFailure，先检查Aws::Auth::AWSCredentials中的 access key / secret key 是否与 MinIO 控制台一致，大小写敏感
分片上传要用 UploadPart，不是 PutObject
UploadPart 是唯一支持分片的接口，每个分片需独立构造请求，并传入 uploadId、partNumber（从 1 开始递增）、body（该分片的二进制流）和 contentLength。SDK 不会帮你拆流，你得自己用 std::ifstream 定位 + read() 截取字节块。
- MinIO 要求每个分片最小 5MB（除最后一片），否则
UploadPart返回EntityTooSmall -
partNumber必须是 1–10000 范围内的整数，跳号或重复会导致CompleteMultipartUpload失败 - 建议用
Aws::MakeShared<:stringstream>包裹分片数据，避免生命周期管理出错；别用栈上临时std::string直接赋给SetBody() - 并发上传多个分片时，每个
UploadPartRequest必须是独立对象实例，共享同一S3Client没问题，但别复用 request 对象
CompleteMultipartUpload 前必须收集全部 Etag
每个成功的 UploadPart 响应里都有一个 Etag 字段（注意：不是 MD5，是 MinIO 计算的分片校验值，形如 "d41d8cd98f00b204e9800998ecf8427e"），CompleteMultipartUpload 必须把每个分片的 partNumber 和对应 Etag 打包进 CompletedMultipartUpload 结构体，顺序无关，但缺一不可。
- 漏传某个
partNumber或填错Etag，会报InvalidPart错误，整个上传任务作废，得重来 - MinIO 不支持
ListParts查询已上传分片（部分旧版有 bug），所以你的代码必须自己缓存每片的partNumber和返回的Etag - 如果某分片上传失败，可重试同
partNumber，MinIO 允许覆盖；但不要擅自跳过失败分片直接Complete，否则文件损坏
MinIO 环境下容易忽略的配置细节
aws-sdk-cpp 默认走 HTTPS + SSL 校验，而本地 MinIO 通常用 HTTP + 自签名证书，不处理会卡在连接阶段或报 CurlHttpError。
- 务必在
Aws::Client::ClientConfiguration中设cfg.scheme = Aws::Http::Scheme::HTTP和cfg.verifySSL = false - MinIO endpoint 地址不能带
http://前缀，只写"127.0.0.1:9000"或"minio.local:9000"，否则 SDK 会拼出http://http://...导致解析失败 - Debug/Release 混链 SDK 库必崩：确保
aws-cpp-sdk-core.lib和aws-cpp-sdk-s3.lib都是同一编译模式（/MD 或 /MT），且与你的项目一致；否则std::shared_ptr跨 DLL 边界析构会 crash
真正麻烦的不是 API 调用本身，而是分片边界计算、并发控制、失败重试策略和 Etag 的可靠传递——这些逻辑一旦写错，上传成功却文件损坏，比上传失败更难排查。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
