安装

准备工作

• 使用RAM用户或STS方式访问

  由于阿里云账号AccessKey拥有所有API访问权限，建议遵循阿里云安全最佳实践。如果部署在服务端可以使用RAM用户或STS来进行API访问或日常运维管控操作，如果部署在客户端请使用STS方式来进行API访问。更多信息，请参见访问控制。

• 设置跨域资源共享（CORS）

  具体操作，请参见设置跨域资源共享。

  通过浏览器直接访问OSS时，CORS配置规则要求如下：

  • 来源：设置精准域名（例如www.aliyun.com）或带有通配符星号（*）的域名（例如*.aliyun.com）。
  • 允许Methods：请根据实际使用场景，选择不同的Methods。例如分片上传时，设置为PUT；删除文件时，设置为DELETE。
  • 允许Headers：设置为*。
  • 暴露Headers：设置为ETag、x-oss-request-id和x-oss-version-id。
  

注意事项

OSS Browser.js SDK通过Browserify和Babel产生适用于浏览器的代码。由于浏览器环境的特殊性，无法使用以下功能：

• 流式上传：浏览器中无法设置chunked编码，建议使用分片上传替代。
• 操作本地文件：浏览器中不能直接操作本地文件系统，建议使用签名URL的方式下载文件。
• 由于OSS暂时不支持Bucket相关的跨域请求，建议在控制台执行Bucket相关操作。

下载SDK

目前官网文档中的demo都是基于SDK 6.x，版本低于6.x的可参考 5.x开发文档，如果要升级到6.x请参考升级文档。

• Github地址
• API使用说明
• ChangeLog

安装SDK

• 支持的浏览器
  • IE(>=10)和Edge
  • 主流版本的Chrome、Firefox、Safari
  • 主流版本的Android、iOS、WindowsPhone系统默认浏览器
• 安装方式

  Browser.js SDK的安装方式有以下几种：

  • 浏览器引入
    注意 因为部分浏览器不支持promise，需要引入promise兼容库。 例如IE10和IE11需要引入promise-polyfill。

    <!-- 引入在线资源 -->
    <script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-x.x.x.min.js"></script>                           

    <!-- 引入本地资源 -->
    <script src="./aliyun-oss-sdk-x.x.x.min.js"></script>                           

    说明

    • 引入在线资源方式依赖于CDN服务器的稳定性，推荐用户使用离线方式引入，即通过本地资源或自行构建的方式引入。
    • 使用引入本地资源方式时，src请填写本地资源相对于示例程序的相对路径。
    • src中的aliyun-oss-sdk-x.x.x.min.js为资源名称，其中x.x.x代表版本号，具体版本信息请参见访问查看 。
    在代码中使用OSS对象：

    说明 关于搭建STS服务的具体操作，请参见开发指南中的使用STS临时访问凭证访问OSS。您可以通过调用STS服务的AssumeRole接口或者使用各语言STS SDK来获取临时访问凭证。临时访问凭证包括临时访问密钥（AccessKeyId和AccessKeySecret）和安全令牌（SecurityToken）。临时访问凭证有效时间单位为秒，最小值为900，最大值以当前角色设定的最大会话时间为准。更多信息，请参见设置角色最大会话时间。

    <script type="text/javascript">
      const client = new OSS({
        // yourRegion填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou。
        region: 'yourRegion',
        // 从STS服务获取的临时访问密钥（AccessKey ID和AccessKey Secret）。
        accessKeyId: 'yourAccessKeyId',
        accessKeySecret: 'yourAccessKeySecret',
        // 从STS服务获取的安全令牌（SecurityToken）。
        stsToken: 'yourSecurityToken',
        refreshSTSToken: async () => {
        // 向您搭建的STS服务获取临时访问凭证。
          const info = await fetch('your_sts_server');
          return {
            accessKeyId: info.accessKeyId,
            accessKeySecret: info.accessKeySecret,
            stsToken: info.stsToken
          }
        },
        // 刷新临时访问凭证的时间间隔，单位为毫秒。
        refreshSTSTokenInterval: 300000,
        // 填写Bucket名称。
        bucket: 'examplebucket'
      });
    </script>                           

  • 使用npm安装SDK开发包

    npm install ali-oss                           

    成功安装完成后，即可使用import或require进行引用。由于浏览器中原生不支持require模式，因此需要在开发环境中配合相关的打包工具，例如webpack、browserify等。

    const OSS = require('ali-oss');
    
    const client = new OSS({
        // yourRegion填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou。
        region: 'yourRegion',
        // 从STS服务获取的临时访问密钥（AccessKey ID和AccessKey Secret）。
        accessKeyId: 'yourAccessKeyId',
        accessKeySecret: 'yourAccessKeySecret',
        // 从STS服务获取的安全令牌（SecurityToken）。
        stsToken: 'yourSecurityToken',
        refreshSTSToken: async () => {
        // 向您搭建的STS服务获取临时访问凭证。
          const info = await fetch('your_sts_server');
          return {
            accessKeyId: info.accessKeyId,
            accessKeySecret: info.accessKeySecret,
            stsToken: info.stsToken
          }
        },
        // 刷新临时访问凭证的时间间隔，单位为毫秒。
        refreshSTSTokenInterval: 300000,
        // 填写Bucket名称。
        bucket: 'examplebucket'
    });

使用方式

OSS Browser.js SDK支持同步和异步的使用方式。

• 同步方式：基于ES7规范的async/await，使得异步方式同步化。
• 异步方式：与Callback方式类似，API接口返回Promise，使用then()处理返回结果，使用catch()处理错误。

以下是使用同步或者异步方式上传文件，然后下载文件的示例说明。

• 同步方式

  // 实例化OSS Client。
  const client = new OSS(...);
  
  async function put () {
    try {
      // object表示上传到OSS的文件名称。
      // file表示浏览器中需要上传的文件，支持HTML5 file和Blob类型。
      const r1 = await client.put('object', file);
      console.log('put success: %j', r1);
      const r2 = await client.get('object');
      console.log('get success: %j', r2);
    } catch (e) {
      console.error('error: %j', e);
    }
  }
  
  put();                    

• 异步方式

  // 实例化OSS Client。
  const client = new OSS(...);
  
  // object表示上传到OSS的文件名称。
  // file表示浏览器中需要上传的文件，支持HTML5 file和Blob类型。
  client.put('object', file).then(function (r1) {
    console.log('put success: %j', r1);
    return client.get('object');
  }).then(function (r2) {
    console.log('get success: %j', r2);
  }).catch(function (err) {
    console.error('error: %j', err);
  });