前端上传图片、视频或附件时,常见做法是先把文件发到业务服务器,再由服务器转存到阿里云 OSS。文件数量或体积增加后,这条链路会占用服务器带宽,也会增加处理压力。使用阿里云 OSS JS SDK,浏览器可以在临时授权下直接上传文件,业务服务器负责验证用户身份并签发临时凭证。
浏览器端代码对用户可见,不能把长期 AccessKey 写进网页或打包文件里。密钥一旦泄露,存储资源就可能被未授权访问或滥用。使用阿里云 oss js 时,先把授权方式设计好,再接入上传功能,后续处理跨域、文件命名和失败重试会更顺畅。
阿里云 OSS JS 能用于哪些场景
阿里云 OSS JS 通常指 JavaScript 项目使用的 OSS 客户端 SDK,可用于 Node.js,也可用于浏览器。前端项目常用它上传头像、商品图片、文档和媒体文件;服务端项目则可用来上传、下载、列举或删除对象。
SDK 封装了对象存储接口,开发者可以通过统一的方式配置存储空间、上传对象,并处理进度等状态。大文件或网络不稳定时,也可以结合 SDK 能力设计分片上传和断点续传。具体参数及支持情况会随 SDK 版本变化,接入前应核对项目所用版本的官方文档。
浏览器直传 OSS 的流程
- 用户选择文件:前端读取文件,并按业务要求检查格式和大小。这里的检查主要用于及时提示用户,不能代替服务端的安全校验。
- 前端申请临时凭证:浏览器向业务接口请求上传授权。后端验证用户身份和操作权限,再获取短时有效的访问凭证。
- 创建 OSS 客户端:前端使用临时凭证、地域和 Bucket 等信息初始化客户端。
- 上传并保存对象信息:文件写入指定对象路径,页面可以显示上传状态;上传完成后,业务系统保存对象名或相关信息。
长期密钥应留在服务端。后端签发临时凭证时,还要限制有效期、可访问的 Bucket、允许执行的操作和写入路径。临时凭证并不代表没有风险,授权范围过大时,凭证泄露仍可能造成损失。
阿里云 OSS JS 前端接入示例
先安装 SDK:npm install ali-oss。浏览器项目还要确认当前构建工具能正确打包依赖。以下示例省略了后端接口,只展示前端拿到临时凭证后的调用方式:
const auth = await fetch(‘/api/oss/sts’).then(r => r.json());
const client = new OSS({
region: auth.region,
bucket: auth.bucket,
accessKeyId: auth.accessKeyId,
accessKeySecret: auth.accessKeySecret,
stsToken: auth.securityToken
});
const objectName = ‘uploads/’ + Date.now() + ‘-‘ + file.name;
const result = await client.put(objectName, file);
console.log(result.name);
示例中的 auth 应由自己的服务端接口返回,包含短期有效的临时凭证,不能替换成固定的账号密钥。objectName 只是演示用途:生产环境要考虑文件名中的特殊字符、重名冲突和目录规划。浏览器上传的文件名、类型和大小都不能直接视为可信信息;前端校验可以改善使用体验,关键限制仍应由服务端或存储授权策略落实。
需要展示进度时,可以使用当前 SDK 版本提供的进度回调更新页面状态。上传完成后,业务系统通常保存对象名,避免把业务逻辑完全绑定到可能变化的完整 URL。图片访问地址则可根据 Bucket 权限、域名和 CDN 配置生成。
接入时容易漏掉的细节
不要把长期密钥放进前端
AccessKey、Secret 和长期授权信息都不应出现在前端源码、公开仓库或浏览器实际加载的构建产物中。前端环境变量也可能被打包进网页,并不会因为名称写在环境变量里就自动安全。应由后端完成身份校验,再按用户和业务场景签发临时凭证。
OSS 跨域规则要和实际域名匹配
浏览器跨域上传需要在 OSS 跨域规则中配置允许的来源、请求方法和相关请求头。正式环境应尽量填写实际使用的域名,避免为了省事开放给所有来源。还要区分跨域配置和权限控制:跨域规则允许浏览器发起请求,不代表请求本身获得了合适的授权。
先确定对象命名和覆盖规则
如果每次上传都使用相同对象名,新文件可能覆盖旧文件。可以由后端生成带随机标识的对象名,降低重名风险,也方便后续管理。文件替换、删除、类型限制和失败后清理等规则,最好在接入时一并考虑。
大文件需要测试失败恢复
几张小图片通常可以从普通上传开始;视频和大型压缩包则应评估分片上传、失败重试和断点续传。网络断开后能否恢复,取决于具体实现与 SDK 配置,不能因为接入了 SDK 就默认具备完整的续传体验。上线前应在目标浏览器和实际网络环境中测试。
用商品图片上传看完整链路
以电商后台上传商品图片为例:运营人员登录后选择图片,前端先提示文件过大或格式不支持。检查通过后,前端向业务服务申请临时凭证;服务端确认用户有商品编辑权限,再签发限定操作范围的凭证。浏览器将图片上传到 OSS,成功后把对象名提交给商品保存接口。商品详情页需要展示图片时,再根据存储策略生成访问地址。
图片不必经过业务服务器转发,后端仍能确认用户是否有上传权限,并记录对应的业务操作。上传失败时,页面可以提供重试;凭证过期时,前端重新向业务接口申请即可,不需要长期持有高权限密钥。
把上传链路分步做稳
阿里云 OSS JS 可以让 JavaScript 项目直接接入对象存储,但接入工作不止是调用 put 方法。临时授权、权限范围、跨域规则、对象命名和失败处理都会影响实际使用。可以先用小文件跑通“后端签发凭证、前端上传、业务保存对象名”的完整流程,再按文件大小和页面体验补充进度反馈或分片上传能力。