网页上传头像、图片或业务附件时,常见做法是先把文件传到应用服务器,再由服务器转存到对象存储。文件量增加后,这条链路会占用服务器带宽,也增加维护环节。使用阿里云 OSS JavaScript SDK,浏览器可以直接把文件上传到 OSS,减轻应用服务器的传输负担。
直传并不意味着把存储权限交给浏览器。前端代码会被访问者查看,密钥、上传范围和文件访问方式都要提前设计好。接入时,除了调用上传接口,还要检查临时凭证、RAM 权限、跨域规则,以及失败后的处理方式。
浏览器为什么要使用 OSS JavaScript 客户端
阿里云 OSS 提供 JavaScript SDK,网页应用可以通过它上传、下载、删除文件,也可以进行分片上传。常见的浏览器直传流程是:前端向业务后端申请临时凭证,后端确认用户身份并签发权限受限的凭证;前端再用凭证初始化 OSS 客户端,将文件上传到指定 Bucket。
不要把 AccessKey ID 和 AccessKey Secret 写进前端代码。网页脚本可以被任何访问者查看,长期密钥一旦泄露,攻击者就可能在密钥权限范围内读取、删除或上传文件。应由后端通过 STS 签发短时有效的临时凭证,并限制它能访问的 Bucket、目录和操作。
接入前要准备哪些配置
- 创建 OSS Bucket,并确认实际地域、存储类型和读写权限。通常可将 Bucket 保持为私有,再按业务需要生成签名 URL。
- 在 RAM 中配置最小权限策略,只允许访问指定 Bucket 或目录,并限制可执行的操作。不要为了省事直接授予整个 Bucket 的读写权限。
- 由后端提供临时凭证接口,返回 STS 凭证、过期时间、Bucket 和地域等信息。接口需要先确认用户已登录,并按用户或业务场景限制上传范围。
- 在 OSS 控制台配置跨域规则,填写实际使用的网页来源、请求方法和必要请求头,不要用宽泛配置代替权限控制。
地域必须与 Bucket 所在地域一致,Bucket 名称也要准确。跨域规则只决定浏览器是否允许网页发起跨域请求,并不会授予对象读写权限,也不会让私有文件自动公开。遇到浏览器跨域报错时,应核对来源、方法和请求头;遇到权限错误,则要检查 STS 策略和对象路径。
JavaScript 上传示例
以下代码假设项目已经安装并引入阿里云 OSS JavaScript SDK。使用浏览器构建工具时,应按项目的依赖管理方式安装和打包 SDK。示例中的 sts 数据由业务后端安全返回,不能替换成写在前端的长期密钥。
const client = new OSS({
region: ‘oss-cn-hangzhou’,
bucket: ‘example-bucket’,
accessKeyId: sts.accessKeyId,
accessKeySecret: sts.accessKeySecret,
stsToken: sts.securityToken
});
const file = input.files[0];
const key = ‘uploads/’ + crypto.randomUUID() + ‘-‘ + file.name;
const result = await client.put(key, file);
console.log(result.name);
对象名加入随机标识,可以减少不同用户上传同名文件时互相覆盖的情况。示例中的 crypto.randomUUID() 需要目标浏览器支持;不支持时,可在项目中使用可靠的 UUID 库。用户提供的文件名也不宜未经处理就拼进对象路径,应考虑特殊字符、路径分隔符和可能暴露的个人信息。
前端可以先检查文件大小和类型,及时给用户提示,但这不能代替服务端限制。后端签发凭证时仍应限制可写入的目录,并设置合理的有效期;如果业务要求只允许特定格式或大小,还要在服务端流程中落实相应校验。
头像上传时,上传成功还不等于业务完成
以个人资料页更换头像为例:用户选中文件后,前端检查图片类型和大小,再向后端申请上传凭证。后端确认登录状态后,签发只能写入该用户头像目录的短期 STS 凭证。前端完成上传后,再把对象 Key 提交给业务接口,由后端更新头像记录。
这两个步骤应分别处理。对象已经上传、数据库记录却没有更新时,页面可能仍显示旧头像,还会留下没有业务记录关联的文件。可以在业务提交失败时提示用户重试,并安排清理未关联对象的任务。展示头像时,如果 Bucket 为私有,后端可根据对象 Key 生成有时效的签名 URL;若采用公开读取,也只开放确有需要的资源。
大文件、进度和失败处理
普通的 put 适合常见的小文件。文件较大或网络不稳定时,可以考虑 SDK 提供的分片上传能力,并通过进度回调更新页面状态。上传界面应明确显示进度、失败提示和重试入口,避免用户看不到反馈后反复点击,生成多个对象。
重试前要想好对象 Key 的规则。沿用同一个 Key,便于把重试与原操作关联起来;若每次重试都生成新 Key,则需要能够追踪并清理重复对象。网络错误、凭证过期、权限不足和跨域配置错误也要区别处理:凭证过期时重新向后端申请,权限不足时检查 RAM 策略和目标路径,跨域问题则核对 OSS 的 CORS 配置。
日志中不要记录完整临时凭证、敏感请求信息或不应公开的文件地址。排查问题时,记录错误类型和必要的业务关联信息即可,避免调试日志本身成为新的泄露入口。
上线前的检查项
- 浏览器报跨域错误:检查 CORS 规则是否包含当前网站域名、实际使用的方法和必要请求头。
- 上传返回权限错误:核对 STS 策略、Bucket 名称、地域、对象 Key 范围和凭证有效期。
- 上传成功但图片无法访问:确认 Bucket 是否为私有;私有对象需要签名 URL 或经过授权的下载接口,不能直接把对象地址当作公开链接。
- 文件被覆盖或出现重复对象:检查对象 Key 是否包含随机标识、用户标识或业务记录 ID,并确认重试时采用的命名规则。
上线前还应测试大文件、网络中断、凭证过期和重复提交等情况,并确认前端拿到的权限没有超出业务需要。阿里云 OSS JavaScript 接入本身并不复杂,凭证生命周期、可写入范围和异常处理,决定了浏览器直传是否安全、稳定,也决定后续排查问题时是否有清晰的处理路径。