原理篇二：大文件分块上传
更新时间：2025-08-21
原理篇二：大文件分块上传
用户在使用浏览器上传文件到 BOS 的时候，如果遇到文件过大，需要先将文件分块然后再上传。上传过程中有可能会遇到页面关闭、浏览器崩溃、网络连接中断等问题，从而导致上传失败。BOS 支持分块上传和断点续传功能。分块上传请参见“ Object 的分块上传”，下面介绍“断点续传”的实现方法。
实现原理
在我们使用文件分块上传（multipartUpload）的时候， BOS 首先会为这个上传过程分配一个 uploadId 。然后我们将一个文件被分成了若干 part ，每个 part 独立上传，上传完成后，BOS 服务会为这个 part 生成一个 eTag 。当所有 part 都上传完成的时候，BOS 服务根据这些 eTag 和 uploadId 把正确的 part 找出来，并组合成原本的文件。
在这个过程中，BOS 并不需要所有的 part 一下子全部上传完毕，而是可以分多次进行。这也就是说，上传过程中，当页面意外关闭时，我们可以不必从头开始重新上传，而只需要把未上传成功的 part 的再次上传就可以。当然，前提是我们需要把此次上传的 uploadId 和上传完成的 part 的 etag 保存下来（不过，更推荐的做法是通过 listParts 接口来查询更精确的已上传分块信息）。在上传一个 part 之前，可以先检查一下，这个 part 是否已经上传过了，如果以前已上传成功，那就直接跳过这个 part 的上传过程。
对于 uploadId 的存储，需要满足不受页面关闭的影响，比较理想的做法是存储在 localStorage 中。
本地存储
在保存 uploadId 时，我们需要为它指定一个 key ，让不同的文件、不同的上传过程区分开。本示例采用文件名、文件大小、分区大小、 bucket 名称、 object 名称组合成这个 key ：
Plain Text
1var generateLocalKey = function (blob, chunkSize, bucket, object) {
2 return [blob.name, blob.size, chunkSize, bucket, object].join('&');
3 };注意：用这个方式生成的 key 并不准确，如果两次上传过程中，选择了两个文件名相同、文件大小相同，但内容不同的文件，那么用这样的方式并不能正确区分这两个文件。更严谨的方式是根据文件名和文件内容计算 MD5 ，并以此为 key 。
存储方式我们选择 localStorage ：
Plain Text
1var getUploadId = function (key) {
2 return localStorage.getItem(key);
3 };
4var setUploadId = function (key, uploadId) {
5 return localStorage.setItem(key, uploadId);
6 };
7var removeUploadId = function (key) {
8 return localStorage.removeItem(key);
9 };初始化分块上传
在初始化分块上传时，有两种可能：
- 如果已经存在此文件的 uploadId ，那么跳过 initiateMultipartUpload() 方法，改为调用 listParts() 来获取已上传分块信息；
- 如果没有此文件的 uploadId，那么调用 initiateMultipartUpload() 方法获得新的 uploadId ，并将这个 uploadId 保存在 localStorage 中。
Plain Text
1 // ...省略BosClient初始化过程
2 // var bosClient = new BosClient(bosConfig);
3
4 var initiateMultipartUpload = function (file, chunkSize, bucket, object) {
5 // 根据文件生成localStorage的key
6 var key = generateLocalKey(file, chunkSize, bucket, object);
7 // 获取对应的`uploadId`
8 var uploadId = getUploadId(key);
9 if (uploadId) {
10 // `uploadId`存在，说明有未完成的分块上传。
11 // 那么调用`listParts()`获取已上传分块信息。
12 return BosClient.listParts(bucket, object, uploadId)
13 .then(function (response) {
14 // response.body.parts里包含了已上传分块的信息
15 response.body.uploadId = uploadId;
16 return response;
17 });
18 }
19 else {
20 // `uploadId`不存在，那么用正常的流程初始化
21 return BosClient.initiateMultipartUpload(bucket, object)
22 .then(function (response) {
23 // response.body.uploadId为新生成的`uploadId`
24 response.body.parts = [];
25 // 为了下次能使用断点续传，我们需要把新生成的`uploadId`保存下来
26 setUploadId(key, response.body.uploadId);
27 return response;
28 });
29 }
30 }分块上传
在对大文件分割分块时，我们可以跟以上传的分块列表进行比较，以确定是否需要真的进行上传。
Plain Text
1 function getEtag(partNumber, parts){
2 // 从已上传part列表中找出特定partNumber的part的eTag
3 for(var i = 0, l = parts.length; i < l; i++){
4 if (parts[i].partNumber === partNumber) {
5 return parts[i].eTag;
6 }
7 }
8 return null;
9 }
10 function getTasks (file, uploadId, chunkSize, bucket, object, parts) {
11 var leftSize = file.size;
12 var offset = 0;
13 var partNumber = 1;
14
15 var tasks = [];
16
17 while (leftSize > 0) {
18 var partSize = Math.min(leftSize, chunkSize);
19 var task = {
20 file: file,
21 uploadId: uploadId,
22 bucket: bucket,
23 object: object,
24 partNumber: partNumber,
25 partSize: partSize,
26 start: offset,
27 stop: offset + partSize - 1
28 };
29
30 // 如果在已上传完成的分块列表中找到这个分块的etag，那么记录下来
31 var etag = getEtag(partNumber, parts);
32 if (etag){
33 task.etag = etag;
34 }
35 tasks.push(task);
36 leftSize -= partSize;
37 offset += partSize;
38 partNumber += 1;
39 }
40 return tasks;
41 }
42
43在进行分块上传处理的时候，根据是否已带有etag字段来决定是否需要上传：
44
45 function uploadPartFile(state, bosClient) {
46 return function(task, callback) {
47 if (task.etag) {
48 // 如果有etag字段，则直接跳过上传
49 callback(null, {
50 http_headers: {
51 etag: task.etag
52 },
53 body: {}
54 });
55 }
56 else {
57 // 否则进行上传
58 var blob = task.file.slice(task.start, task.stop + 1);
59 bosClient.uploadPartFromBlob(task.bucketName, task.key, task.uploadId, task.partNumber, task.partSize, blob)
60 .then(function(res) {
61 ++state.loaded;
62 callbacknull(res);
63 })
64 .catch(function(err) {
65 callback(err);
66 });
67 }
68 };
69 }流程代码
我们对每个步骤的代码做了一些小修改，但整个流程的代码与分块上传很类似：
Plain Text
1 var chunkSize = 5 * 1024 * 1024; // 分块大小
2 var uploadId;
3 initiateMultipartUpload(file, chunkSize, bucket, object)
4 .then(function(response) {
5 uploadId = response.body.uploadId; // uploadId，可能是服务器刚刚生成的，也可能是从localStorage获取的
6 var parts = response.body.parts || []; // 已上传的分块列表。如果是新上传，则为空数组
7 var deferred = sdk.Q.defer();
8 var tasks = getTasks(blob, uploadId, chunkSize, bucket, key, parts);
9 var state = {
10 lengthComputable: true,
11 loaded: parts.length, // 已上传的分块数
12 total: tasks.length
13 };
14 // 如果已上传的分块数大于0，可以先修改一下文件上传进度
15 bosClient.emit('progress', state);
16 // 为了管理分块上传，使用了async（https://github.com/caolan/async）库来进行异步处理
17 var THREADS = 2; // 同时上传的分块数量
18 async.mapLimit(tasks, THREADS, uploadPartFile(state, bosClient), function(err, results) {
19 if (err) {
20 deferred.reject(err);
21 } else {
22 deferred.resolve(results);
23 }
24 });
25 return deferred.promise;
26 })
27 .then(function(allResponse) {
28 var partList = [];
29 allResponse.forEach(function(response, index) {
30 // 生成分块清单
31 partList.push({
32 partNumber: index + 1,
33 eTag: response.http_headers.etag
34 });
35 });
36
37 // 所有分块上传完成后，可以删除对应的`uploadId`了
38 removeUploadId(key, uploadId);
39
40 return bosClient.completeMultipartUpload(bucket, key, uploadId, partList); // 完成上传
41 })
42 .then(function (res) {
43 // 上传完成
44 })
45 .catch(function (err) {
46 // 上传失败，添加您的代码
47 console.error(err);
48 });