文件上传时,用户想知道文件是否还在传,以及出错后能不能重试。小文件可能很快完成,几十兆的视频或几个 G 的压缩包却可能需要等待一段时间。页面没有反馈,用户容易以为任务卡住,反复点击上传。
以下以浏览器直传阿里云 OSS 为例,说明如何用 SDK 的进度回调更新界面,以及大文件上传时需要留意的状态、重试和权限问题。不同版本的 SDK 在接口和参数上可能有差异,接入时应核对项目正在使用的阿里云 OSS SDK 文档。
进度条显示的是什么
常见的上传进度按“已传输的数据量 ÷ 文件总大小”计算。比如一个 10MB 的文件已经传了 4MB,页面可以显示约 40%。这个百分比反映传输进度,不代表剩余时间;网络速度会变化,SDK 也可能重试,因此进度不一定匀速增长。
分片上传时,SDK 会把大文件拆成多个分片,必要时还会并行上传。界面显示的进度通常表示当前累计完成的传输量。网络波动时进度停顿一会儿,并不一定代表任务失败。除了百分比,页面最好同时显示“上传中”“已完成”或“失败”等状态。进度回退或任务重新开始时,也要避免让用户误以为上传已经完成。
用 SDK 进度回调更新界面
使用阿里云 OSS JavaScript SDK 时,可以在上传过程中监听进度回调。以分片上传为例,调用 multipartUpload 后,SDK 会提供上传进度信息;前端根据回调结果更新百分比和状态文字。页面无需自行估算速度,也不要靠定时器猜测上传进度。
用户选中文件后,先把进度设为 0,状态设为“待上传”;开始请求后改为“上传中”。收到进度回调时,读取当前进度并更新页面。上传调用正常完成后,再把进度设为 100%、状态改为“已完成”;如果调用抛出异常,则显示失败状态,并提供重试或取消入口。
回调中的进度值通常在 0 到 1 之间,乘以 100 就能换算成百分比。显示时可以取整,并把数值限制在 0 到 100 之间。进度到达 100% 仍不代表上传一定成功:应等上传调用正常结束,再执行后续业务操作,例如登记文件信息。
浏览器直传 OSS 还涉及凭证安全。不要把长期有效的 AccessKey ID 和 AccessKey Secret 写进前端代码。常见做法是由业务后端校验用户身份并签发短时有效的临时凭证,前端拿到凭证后再上传。临时凭证的权限应限制在实际需要的 Bucket 和对象路径范围内。
课程视频上传:避免重复提交
设想一个在线课程后台,老师要上传一段 800MB 的教学视频。页面只有“上传”按钮时,如果网络较慢,老师看不到反馈,可能会连续点击。这样会发起多个上传请求,浪费流量,也增加后台处理重复文件的麻烦。
页面可以在选中文件时显示文件名和大小。点击上传后立即禁用按钮,同时显示进度条和“上传中”状态,避免重复提交。SDK 回调负责持续更新百分比;上传完成后,页面再请求业务后端登记文件信息。若上传失败,保留当前文件选择,提示用户检查网络或重新尝试;如果能识别出凭证过期等原因,也可以给出更具体的提示。
对于这类大文件,可以使用分片上传,并在适合的场景中保存续传所需的 checkpoint。网络短暂中断后,用户有机会从已完成的分片继续上传,不必从头开始。续传信息对应具体文件和上传任务,不能直接套用到另一个文件上;用户重新选择文件时,要清理旧任务状态,避免新文件和旧进度混在一起。
进度条之外需要处理的细节
状态和按钮要配合
页面至少应区分“待上传、上传中、已完成、失败”。上传中禁用重复提交,任务完成后再开放下一步操作;失败时提供重试或取消选项。如果支持取消上传,除了停止前端任务,还要根据业务需求清理 OSS 上未完成的分片。
不要用定时器伪造百分比
让进度从 0 慢慢涨到 99% 的定时器,看起来平滑,却不能反映真实传输情况。请求可能已经失败,页面上的数字仍在增长;文件还没传完,进度也可能已经接近 100%。进度应以 SDK 回调为准。若要加平滑动画,只能改善显示效果,不能代替上传结果。
检查 CORS 和上传权限
浏览器请求 OSS 时,Bucket 的 CORS 规则需要允许业务站点的来源、所用请求方法和必要请求头。规则不匹配时,浏览器可能拦截请求或无法正常读取结果。也要检查临时凭证是否具备目标 Bucket 和对象路径所需权限。排查问题时不要为了省事开放所有操作,权限应限于业务实际需要的范围。
区分用户提示和排查日志
网络断开、临时凭证过期、Bucket 配置不正确、文件超出限制,都可能导致上传失败。页面可以提示“上传中断,请检查网络后重试”;开发人员则需要在日志中记录错误码、文件大小和上传任务标识,便于定位问题。日志和页面都不要暴露敏感凭证或完整授权信息。
上线前检查
- 确认进度来自 SDK 上传回调,而不是定时器模拟。
- 等上传调用成功后再登记业务记录,避免失败任务被标记为完成。
- 测试小文件、大文件、慢速网络和中断重试。
- 检查临时凭证有效期、上传权限和 OSS CORS 配置是否符合实际场景。
- 确认重复点击、取消上传和重新选择文件时,页面状态都能正确重置。
普通小文件可以先接入 SDK 回调和基础状态提示;视频、压缩包等大文件,还要考虑分片、续传和未完成分片的清理。阿里云上传进度条应显示真实进度,并明确反馈上传成功或失败,让用户知道任务进展,也方便开发人员排查异常。