当文件较大、上传时间较长或网络不稳定时，分段上传通常比单次上传更稳定，也更适合大文件业务和 AI 数据导入。
当文件体积较大时，单次上传对网络波动非常敏感。分段上传可以把一次失败收敛到少量分段，而不是整文件重传。
视频源文件、模型权重、训练数据集这类文件通常上传时间较长。分段上传更容易实现进度、重试和断点续传能力。
系统已经具备任务队列或 AI 工作流时，大文件写入存储服务通常更适合使用分段上传，而不是单次 PUT。
常见起点是 8MB 到 32MB。过小会带来过多请求，过大又会降低失败重试的收益。
浏览器一般建议 3 到 6 个并发分段，任务机或后端服务可以根据网络和机器资源适度提高。
初始化时就确定 objectKey，不要让每个分段单独决定路径。大文件尤其需要稳定的目录和命名规则。
POST /api/storage/multipart/init
{
"fileName": "training-dataset.zip",
"contentType": "application/zip",
"size": 2684354560
}
{
"success": true,
"uploadId": "upload_xxx",
"bucket": "training-assets",
"objectKey": "datasets/project-a/2026-06/training-dataset.zip",
"partSize": 10485760,
"requestId": "req_xxx"
}PUT uploadUrl(partNumber=1) Content-Type: application/zip <binary chunk>
POST /api/storage/multipart/complete
{
"uploadId": "upload_xxx",
"objectKey": "datasets/project-a/2026-06/training-dataset.zip",
"parts": [
{ "partNumber": 1, "etag": "etag-1" },
{ "partNumber": 2, "etag": "etag-2" }
]
}由服务端生成 uploadId、objectKey、partSize 和 requestId。浏览器或任务机只消费这些结果，不自行决定分段规则。
POST /api/storage/multipart/init
{
"fileName": "training-dataset.zip",
"contentType": "application/zip",
"size": 2684354560
}
{
"success": true,
"uploadId": "upload_xxx",
"bucket": "training-assets",
"objectKey": "datasets/project-a/2026-06/training-dataset.zip",
"partSize": 10485760,
"requestId": "req_xxx"
}每个分段都应拿到自己的 uploadUrl 或上传参数，成功后记录 partNumber 与 etag，供 complete 阶段使用。
PUT uploadUrl(partNumber=1) Content-Type: application/zip <binary chunk>
complete 不是可选步骤。只有当全部分段的 etag 都被提交并完成合并，文件才真正成为可下载、可读取的完整内容。
POST /api/storage/multipart/complete
{
"uploadId": "upload_xxx",
"objectKey": "datasets/project-a/2026-06/training-dataset.zip",
"parts": [
{ "partNumber": 1, "etag": "etag-1" },
{ "partNumber": 2, "etag": "etag-2" }
]
}实际上传时，建议由前端或任务系统按段提交，并在全部成功后统一调用 complete。
for (const part of parts) {
const chunk = file.slice(part.start, part.end);
const response = await fetch(part.uploadUrl, {
method: 'PUT',
body: chunk,
});
uploadedParts.push({
partNumber: part.partNumber,
etag: response.headers.get('etag'),
});
}
await fetch('/api/storage/multipart/complete', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
uploadId,
objectKey,
parts: uploadedParts,
}),
});优先检查 parts 数组是否完整、etag 是否来自同一 uploadId，以及 partNumber 是否按正确顺序提交。
优先检查分段大小是否过大、并发数是否过高，以及当前网络环境是否稳定。浏览器同时开启过多分段，反而容易整体变慢。
优先确认本地缓存的 uploadId 是否仍然有效，或者服务端是否已经清理过期上传会话。分段续传必须与同一个 uploadId 对齐。
这通常不是分段上传本身失败，而是 complete 之后没有走业务确认入库，或者文件路径与业务主记录没有绑定起来。
没有绝对阈值，但大文件、长时上传、网络波动较大或需要断点续传的场景，通常更适合使用分段上传。
不一定。浏览器、任务机、容器和后端服务都可以执行分段上传。关键是由服务端统一初始化会话并收口 objectKey。
因为各分段只是临时上传完成，真正的文件要在 complete 之后才会被合并成一个可正常使用的结果。
文档中心帮助你完成接入，客户服务页帮助你了解采购、支持与服务信息。