上传图片时,文件小还不太明显;换成视频或压缩包,页面一直没反应,用户就可能以为卡住了,反复点击上传,甚至直接关掉页面。上传阿里云进度条能让用户看到传输进展,也方便排查上传过程中的问题。不过,进度到 100% 不一定代表文件已经可以使用,页面还需要等 OSS 返回最终结果。
进度条反映的是什么
常见的计算方式是“已上传数据量 ÷ 文件总大小”。比如文件大小为 10MB,客户端已发送 4MB,进度大约是 40%。浏览器或 OSS SDK 提供的上传进度回调,可以用来更新页面上的百分比。
这个数字表示客户端传输进展,不等于文件已经完成校验、写入对象存储并可供访问。实际界面最好把“正在上传”和“正在确认”分开显示:进度到 100% 后,继续等待上传接口返回成功,再提示“上传完成”。否则用户可能看到 100%,打开文件时却发现还不能使用。
先确定上传方式
- 小文件直传:前端使用阿里云 OSS SDK 上传并监听进度,适合图片、文档等常见场景。
- 大文件分片上传:把文件拆成多个分片,按需并发上传,并结合重试或断点续传处理网络中断,适合较大的视频、压缩包。
- 业务服务器中转:浏览器先把文件传给自有服务器,再由服务器上传 OSS。流程直观,但文件流量会经过业务服务器,增加带宽和转发压力。
浏览器直接上传时,通常使用 OSS SDK,并由业务后端提供临时授权。不要把长期 AccessKey 写进前端代码,页面源码可以被查看,凭证泄露后可能导致存储空间被未授权访问或操作。
示例:上传图片并显示进度
下面以活动管理后台上传图片为例,展示主要流程。示例假设项目已安装并正确引入阿里云 OSS JavaScript SDK,且业务后端提供临时凭证接口。接口地址、地域和 Bucket 信息需要按项目配置替换。
<input id="file" type="file" accept="image/*">
<progress id="bar" value="0" max="100"></progress>
<span id="status">等待选择文件</span>
<script>
const input = document.getElementById('file');
const bar = document.getElementById('bar');
const status = document.getElementById('status');
input.addEventListener('change', async () => {
const file = input.files[0];
if (!file) return;
status.textContent = '正在获取上传授权';
bar.value = 0;
try {
const res = await fetch('/api/oss-sts');
if (!res.ok) throw new Error('获取临时凭证失败');
const auth = await res.json();
const client = new OSS({
region: auth.region,
bucket: auth.bucket,
accessKeyId: auth.accessKeyId,
accessKeySecret: auth.accessKeySecret,
stsToken: auth.securityToken
});
const objectName = `images/${Date.now()}-${file.name}`;
status.textContent = '正在上传';
const result = await client.multipartUpload(objectName, file, {
progress: (percent) => {
bar.value = Math.floor(percent * 100);
status.textContent = `正在上传 ${bar.value}%`;
}
});
bar.value = 100;
status.textContent = '上传完成';
console.log('对象信息:', result.name);
} catch (err) {
status.textContent = '上传失败,请重试';
console.error(err);
}
});
</script>
示例里的 percent 通常是 0 到 1 之间的小数,因此乘以 100 后再显示。不同版本的 SDK 在参数和回调格式上可能有差异,接入时要核对对应版本的文档,也要确认项目采用的 SDK 引入方式。
上传成功后,前端可以展示结果,但对象路径、文件类型和业务归属仍应由后端按业务规则确认。不要把前端传来的文件名或其他字段直接当成可信数据。
进度条容易漏掉的细节
上传中和上传成功要分开处理
进度数字只是传输过程的一部分。上传前可以显示“准备中”,传输时更新百分比,到 100% 后改成“正在确认”;只有收到 OSS 或业务接口的成功结果,才显示“上传完成”。发生错误时要给出明确提示,并让用户知道可以重试或重新选择文件。
大文件再考虑分片与续传
普通上传遇到网络中断,可能需要从头再来。分片上传可以分别传输文件的不同部分,失败后按 SDK 支持的方式重试未完成分片;配合检查点,也可以在满足条件时续传。并发数需要结合用户网络和业务负载设置,开得过高可能占满带宽,也会增加浏览器和服务端压力。
临时授权和文件校验由后端把关
临时凭证应由可信的业务后端签发,并限制有效期和可访问范围。后端还应限制上传目录、文件大小和类型。前端检查文件类型可以及时提醒用户,但不能替代服务端校验;只看文件扩展名,也不足以判断文件是否安全。
常见问题排查
- 进度条不动:确认 SDK 的进度回调已注册、上传任务确实启动,再查看浏览器控制台是否出现跨域或授权错误。
- 到 100% 后仍然失败:客户端数据可能已经发出,但分片合并、后续校验或服务端响应仍可能出错。应根据最终 Promise 或接口响应判断结果,不要只看进度数字。
- 浏览器提示跨域错误:检查 OSS Bucket 的跨域规则是否包含当前网页来源、所需请求方法和请求头。配置按实际需求开放即可,避免设置得过宽。
- 刷新后任务丢失:普通页面进度条只记录当前页面状态。需要续传时,要使用 SDK 支持的断点续传能力保存必要任务信息,同时处理凭证过期和文件变化等情况。
小文件上传可以先用 OSS SDK 的进度回调更新页面;文件较大、网络容易中断时,再评估分片上传和断点续传。无论采用哪种方式,都要等到最终接口确认成功后再结束流程,并把授权、跨域和失败重试纳入实际测试。