网站或小程序里的图片、视频和附件如果都经过业务服务器,文件流量也会占用服务器带宽。常见做法是把文件存到阿里云 OSS,再由服务端或浏览器按权限上传、读取。配置好阿里云oss js后,能不能顺利上传,除了调用 SDK,还要看 Bucket 配置、凭证和浏览器跨域规则是否匹配。
阿里云 OSS 和 JavaScript SDK
阿里云对象存储 OSS(Object Storage Service)可以保存图片、文档、音视频等文件。JavaScript 项目通常使用官方 ali-oss SDK 操作 OSS,可用于 Node.js,也可用于浏览器端。常见操作包括上传、下载、删除对象,以及生成带有效期的访问地址。
SDK 负责发起请求,不会替项目自动处理访问权限、CORS 或密钥安全。比如网页上传时,Bucket 没有允许当前网站的跨域请求,浏览器就可能拦截;把长期 AccessKey 写进前端代码,则会让访问者有机会拿到密钥。接入前应把这些配置一并考虑。
开始前准备 Bucket 和凭证
- 创建 Bucket:选择存储地域,并确认文件的访问方式。个人资料、业务附件等私密文件通常不应设为公共读。
- 记下地域和 Bucket 名称:初始化客户端时要使用控制台中的准确值,地域或名称填错都可能导致请求失败。
- 安排凭证发放:长期 AccessKey 不要放进浏览器代码、网页配置或公开仓库。浏览器上传应由业务后端校验用户后,签发短期凭证。
- 配置 CORS:浏览器直接请求 OSS 时,需要在 Bucket 中允许业务网站的来源、请求方法和所需请求头。
Node.js 项目安装并初始化 SDK
在 Node.js 项目中安装 ali-oss:
npm install ali-oss
服务端可以从环境变量读取密钥,避免把凭证写死在源代码里:
const OSS = require('ali-oss');
const client = new OSS({
region: process.env.OSS_REGION,
bucket: process.env.OSS_BUCKET,
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET
});
这段初始化代码应放在受控的服务端环境中。部署时要妥善管理环境变量,并限制密钥的权限和使用范围。网页端不能直接照搬这段配置:浏览器开发者工具可以查看前端代码,长期密钥一旦泄露,就可能被用于未授权操作。
如果由 Node.js 服务端接收文件并上传 OSS,可以在服务端校验用户和文件,再调用 SDK。若要让浏览器直传,则应采用临时凭证流程,避免文件先经过业务服务器,也避免把长期密钥交给用户。
浏览器上传:使用后端签发的临时凭证
浏览器直传通常分成三步:页面向业务后端申请上传凭证;后端检查用户身份和上传权限,再向阿里云 STS 获取有时效、有限权的临时凭证;页面拿到凭证后,使用 SDK 上传文件。凭证过期后不能继续使用,页面需要重新向后端申请。
浏览器端的 SDK 初始化方式会受版本和项目构建环境影响,实际接入时应对照所用版本的官方文档。常见配置包括地域、Bucket 和后端返回的临时身份凭证。不要把临时凭证长期缓存,也不要让用户自行指定不受限制的上传目录。
用户选择文件后,可以由系统生成对象名称,再调用上传方法:
const file = input.files[0];
const objectName = `uploads/${Date.now()}-${file.name}`;
const result = await client.put(objectName, file);
console.log(result.url);
这段代码展示的是基本调用。实际页面还应检查文件是否为空、限制允许的格式和大小,并显示上传进度、失败原因和重试入口。前端校验方便用户及时发现问题,但不能代替服务端授权和必要的文件检查。
活动后台上传海报的处理方式
例如,运营人员要在活动管理后台上传海报。页面先把登录状态交给后端验证,后端确认账号有活动管理权限后,返回短期上传凭证和允许使用的目录。页面拿凭证将图片直接传到 OSS,上传成功后,再把对象名称提交给业务接口。
业务后端可以保存对象名称、活动编号和上传人等信息。展示图片时,再根据 Bucket 的访问策略返回公开地址或签名地址。这样图片文件不必经过业务服务器,业务系统仍然能记录谁上传了什么,也能按自己的权限规则控制展示。
对象名称和目录最好由系统生成,不要直接使用用户提交的完整路径。否则可能出现文件覆盖、目录混乱,或文件被传入不应访问的位置。可以在文件名中加入随机值或唯一标识,同时把用户原始文件名单独保存为业务数据。
上传失败时先检查这些位置
- 浏览器提示跨域错误:检查 Bucket 的 CORS 配置,确认来源、请求方法和请求头都符合当前请求,并留意规则是否已经生效。
- 返回 AccessDenied:检查临时凭证是否过期、授权策略是否覆盖目标 Bucket 和目录,以及当前操作是否在授权范围内。
- 找不到 Bucket 或无法连接:核对 Bucket 名称和地域,也检查当前网络环境。地域标识填错时,请求可能无法正常到达目标存储空间。
- 文件较大或上传时间较长:根据 SDK 支持情况考虑分片上传,并为页面增加进度反馈、失败重试和取消操作。
- 上传成功却打不开:确认对象权限和读取方式。私有文件一般需要通过后端生成有时效的签名 URL,不能把普通对象地址当成公开链接使用。
上线前检查权限和业务记录
临时凭证应按最小权限发放,只开放当前上传需要的 Bucket、目录和操作。私密文件不要设为公共读;签名 URL 要设置合理的有效期,它不是永久访问地址。文件类型和大小限制、上传日志及生命周期规则也要结合业务配置,方便排查问题和清理无用对象。
上传成功只说明文件已存入 OSS,不代表业务流程已经完成。页面可能被关闭,网络可能中断,用户也可能重复提交。业务接口应记录对象名称和上传状态,并处理失败、重复提交等情况。对图片内容有安全要求的项目,还可以在上传后增加服务端审核或扫描流程。