上传头像、商品图或活动照片时,如果先把文件传到业务服务器,再由服务器转存到阿里云 OSS,文件就要经过两次传输。图片数量上来后,服务器也会承担额外的带宽和处理压力。前端直传可以省去这段中转:浏览器把图片直接上传到 OSS,业务后端负责校验用户并签发短时有效的 STS 凭证。
做图片上传阿里云 JS 功能时,有一条不能省的安全要求:不要把长期 AccessKey 写进前端代码。前端代码可以被查看,永久密钥一旦泄露,别人就可能用它访问云资源。
浏览器直传的流程
- 前端向业务后端请求上传凭证,后端先确认用户身份和操作权限。
- 后端通过阿里云 STS 获取临时凭证,并限制它能操作的 Bucket 和对象路径。
- 前端使用 OSS JavaScript SDK 和临时凭证,将图片直接上传到 OSS。
上传完成后,前端通常把对象 key 提交给业务后端保存。图片文件不经过业务服务器,但用户校验、目录规则和业务数据仍由后端管理。临时凭证需要设置合理的有效期和权限范围,不能因为使用 STS 就把整个 Bucket 的操作权限交给浏览器。
准备 OSS Bucket 和跨域规则
先在阿里云控制台创建 OSS Bucket,记下 Bucket 名称和所在地域,例如杭州地域对应的地域标识通常是 oss-cn-hangzhou。前端 SDK 初始化时需要用到这两项信息。
接着配置 Bucket 的跨域规则,允许你的网站域名发起请求,并开放实际使用的方法。SDK 使用 PUT 上传时,需要允许 PUT;如果业务还会读取对象或查询对象信息,再按需开放 GET、HEAD。允许的请求头也应根据实际请求配置。遇到跨域错误时,除了检查规则是否包含当前域名,还要留意预检请求和请求头是否被拦截。
跨域规则只决定浏览器能否跨域发起请求,不负责控制谁有权上传或读取文件。生产环境不要把 Bucket 设置成公共读写。图片需要公开访问时,应按业务选择访问权限或签名 URL 等方式。
后端签发短时有效的 STS 凭证
凭证接口应放在可信的业务后端。后端先确认用户已登录,并检查他是否有上传权限,再通过 STS 获取临时凭证。服务端使用的角色遵循最小权限原则:如果头像只写入 users/ 目录,就尽量不要授权整个 Bucket;商品图片也可以限制在 products/ 等业务目录中。
接口可返回 accessKeyId、accessKeySecret、securityToken、region 和 bucket 等字段。这里的 accessKeySecret 是临时密钥的一部分,前端需要和 securityToken 一起使用。不要把这些凭证长期写入 localStorage 等存储,也不要把永久密钥放进前端项目。
STS 的调用代码会因后端语言和 SDK 而异。不要让浏览器直接请求 STS,也不要提供一个无需登录、任何人都能调用的凭证接口。否则,别人可以反复申请临时凭证,造成资源消耗或上传违规内容。
用 JavaScript SDK 上传图片
项目可以通过 npm 安装 ali-oss。下面的示例假设 /api/oss/sts 会检查当前用户,并返回已授权的临时凭证:
import OSS from ‘ali-oss’;
async function uploadImage(file) {
const resp = await fetch(‘/api/oss/sts’, { credentials: ‘include’ });
if (!resp.ok) throw new Error(‘获取上传凭证失败’);
const auth = await resp.json();
const client = new OSS({
region: auth.region,
bucket: auth.bucket,
accessKeyId: auth.accessKeyId,
accessKeySecret: auth.accessKeySecret,
stsToken: auth.securityToken,
secure: true
});
const ext = file.name.split(‘.’).pop().toLowerCase();
const key = `users/${auth.userId}/${Date.now()}-${crypto.randomUUID()}.${ext}`;
const result = await client.put(key, file, {
progress: (percent) => console.log(‘上传进度:’, Math.round(percent * 100) + ‘%’)
});
return { key: result.name, url: result.url };
}
页面用 input[type=”file”] 获取用户选择的文件,再把 file 传给 uploadImage 即可。示例里的目录和文件名用于说明流程,实际项目要由后端提供或校验用户目录;不能只因为前端提交了某个 key,就认定它有权写入该路径。还要限制文件大小和数量,并校验允许的图片格式。文件扩展名不能单独作为格式校验依据。
上传成功后,result.name 是 OSS 对象 key。业务数据库通常保存 key,而不是只保存完整 URL。以后更换访问域名或调整 CDN 配置时,用 key 生成访问地址会更方便统一管理。
案例:商品后台上传主图
商品后台上传主图时,运营人员选好图片,前端先请求 STS 凭证。后端确认用户已登录且有商品编辑权限,再签发仅允许写入 products/ 目录的短时凭证。图片传到 OSS 后,前端把对象 key 提交给商品保存接口;后端再次检查 key 的目录和用户权限,再将它写入商品记录。
这样,图片文件不需要经过业务服务器,后端仍能把关用户身份和商品数据。若还要做图片审核、压缩或生成缩略图,可以在上传完成后交由服务端任务处理。
常见问题怎么排查
- 浏览器提示跨域错误:检查 OSS 跨域规则中的网站域名、PUT 方法和请求头;规则调整后,也要确认预检请求没有被拦截。
- 返回 AccessDenied:核对 STS 角色策略是否允许向目标路径上传,同时检查 Bucket、地域、对象 key 和凭证有效期。
- 凭证过期后上传失败:重新向后端申请凭证,并创建新的 OSS 客户端再试。不要把临时凭证缓存到过期后继续使用。
- 上传成功但图片打不开:上传成功不代表对象对外公开。私有图片可配合签名 URL;其他访问方式也应按业务权限设置。
上线前检查这些环节
上线前确认后端会校验用户并安全签发 STS 凭证,凭证权限只覆盖必要目录,Bucket 跨域规则与前端请求匹配。前端要能处理上传进度和失败情况,业务后端也要校验提交的对象 key。把这些环节分别处理好,直传既能减少服务器中转开销,也不至于把文件权限交给前端决定。