OSSBrowser.js初始化配置项_对象存储(OSS)-阿里云帮助中心

Client是OSS Browser.js的客户端，用于管理存储空间和文件等OSS资源。使用Browser.js SDK发起OSS请求时，您需要初始化一个Client实例，并根据需要修改默认配置项。

前提条件

已安装Browser.js SDK。具体操作，请参见安装。

新建Client

V4签名（推荐）

推荐使用更安全的V4签名算法。使用V4签名初始化时，需要声明authorizationV4。OSS Browser.js SDK 6.20.0及以上版本支持V4签名。

以使用OSS域名初始化时使用V4签名为例，其他通过自定义域名等初始化的场景可参考以下示例执行相应修改。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <!--导入SDK文件-->
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.20.0.min.js"
    ></script>
    <script type="text/javascript">
      const client = new OSS({
        // yourRegion填写Bucket所在地域。以华东1（杭州）为例，yourRegion填写为oss-cn-hangzhou。
        region: 'yourRegion',
	authorizationV4: true,
        // 从STS服务获取的临时访问密钥（AccessKey ID和AccessKey Secret）。
        accessKeyId: 'yourAccessKeyId',
        accessKeySecret: 'yourAccessKeySecret',
        // 从STS服务获取的安全令牌（SecurityToken）。
        stsToken: 'yourSecurityToken',
        // 填写Bucket名称，例如examplebucket。
        bucket: "examplebucket",
      });
    </script>
  </body>
</html>

V1签名（不推荐）

重要

阿里云对象存储OSS自2025年03月01日起不再对新用户（即新UID ）开放使用V1签名，并将于2025年09月01日起停止更新与维护且不再对新增Bucket开放使用V1签名。请尽快切换到V4签名，避免影响服务。更多信息，请参见公告说明。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <!--导入SDK文件-->
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
    ></script>
    <script type="text/javascript">
      const client = new OSS({
        // yourRegion填写Bucket所在地域。以华东1（杭州）为例，yourRegion填写为oss-cn-hangzhou。
        region: 'yourRegion',
        // 从STS服务获取的临时访问密钥（AccessKey ID和AccessKey Secret）。
        accessKeyId: 'yourAccessKeyId',
        accessKeySecret: 'yourAccessKeySecret',
        // 从STS服务获取的安全令牌（SecurityToken）。
        stsToken: 'yourSecurityToken',
        // 填写Bucket名称，例如examplebucket。
        bucket: "examplebucket",
      });
    </script>
  </body>
</html>

配置Client

您可以在初始化Client时按需添加配置项，例如通过timeout指定请求超时时间，通过stsToken指定临时访问凭证等。关于Browser.js支持的配置项以及配置示例，具体参数请参考下方说明。

options参数说明：

accessKeyId {String}：在阿里云控制台网站上创建的访问密钥。
accessKeySecret {String}：在阿里云控制台创建的访问密钥秘密。
[stsToken] {String}：用于临时授权。
[refreshSTSToken] {Function}：当STS信息过期时自动设置stsToken、accessKeyId、accessKeySecret的函数。返回值必须是包含stsToken、accessKeyId、accessKeySecret的对象。
[refreshSTSTokenInterval] {number}：STS令牌刷新间隔时间（毫秒）。应小于STS信息的过期间隔，默认为300000毫秒（5分钟）。
[bucket] {String}：您想访问的默认Bucket。如果没有Bucket，请先使用putBucket()创建一个。
[endpoint] {String}：OSS区域域名。优先级高于region。根据需要设置为外网域名、内网域名或加速域名等，请参考终端节点列表。
[region] {String}：Bucket数据所在的区域位置，默认为oss-cn-hangzhou。
[internal] {Boolean}：是否通过阿里云内网访问OSS，默认为false。如果您的服务器也在阿里云上运行，可以设置为true以节省大量费用。
[secure] {Boolean}：指示OSS客户端使用HTTPS（secure: true）还是HTTP（secure: false）协议。
[timeout] {String|Number}：针对所有操作的实例级别超时时间，默认为60秒。
[cname] {Boolean}：默认为false，使用自定义域名访问OSS。如果为true，则可以在endpoint字段中填写自定义域名。
[isRequestPay] {Boolean}：默认为false，表示是否开启Bucket的请求者支付功能，如果为true，会向OSS服务器发送头部'x-oss-request-payer': 'requester'。
[useFetch] {Boolean}：默认为false，仅在浏览器环境中生效。如果为true，意味着使用fetch模式上传对象，否则使用XMLHttpRequest。
[enableProxy] {Boolean}：启用代理请求，默认为false。注意启用代理请求时，请确保已安装proxy-agent。
[proxy] {String | Object}：代理URI或选项，默认为null。
[retryMax] {Number}：当请求因网络错误或超时出错时自动重试发送请求的最大次数。不支持流式上传（如put、putStream、append等），因为流只能被消费一次。
[maxSockets] {Number}：每个主机允许的最大套接字数。默认为无限。
[authorizationV4] {Boolean}：使用V4签名。默认为false。

示例

基本用法

const OSS = require('ali-oss');

const store = new OSS({
  region: 'yourRegion',
  authorizationV4: true,
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  stsToken: 'yourSecurityToken',
  bucket: 'your bucket name',
});

使用加速访问endpoint：

说明

全球加速访问endpoint：oss-accelerate.aliyuncs.com

中国内地以外区域的加速访问endpoint：oss-accelerate-overseas.aliyuncs.com

const OSS = require('ali-oss');

const store = new OSS({
  region: 'yourRegion',
  authorizationV4: true,
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  stsToken: 'yourSecurityToken',
  bucket: 'your bucket name',
  endpoint: 'oss-accelerate.aliyuncs.com',
});

使用自定义访问方式

const OSS = require('ali-oss');

const store = new OSS({
  region: 'yourRegion',
  authorizationV4: true,
  stsToken: 'yourSecurityToken',
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  cname: true,
  endpoint: 'your custome domain',
});

使用STS Token访问

const OSS = require('ali-oss');

const store = new OSS({
  region: 'yourRegion',
  authorizationV4: true,
  accessKeyId: 'your STS key',
  accessKeySecret: 'your STS secret',
  stsToken: 'your STS token',
  refreshSTSToken: async () => {
    const info = await fetch('you sts server');
    return {
      accessKeyId: info.accessKeyId,
      accessKeySecret: info.accessKeySecret,
      stsToken: info.stsToken,
    };
  },
  refreshSTSTokenInterval: 300000,
});

使用流重新尝试请求

for (let i = 0; i <= store.options.retryMax; i++) {
  try {
    const result = await store.putStream('<example-object>', fs.createReadStream('<example-path>'));
    console.log(result);
    break; // break if success
  } catch (e) {
    console.log(e);
  }
}

使用V4签名，并使用可选的additionalHeaders选项（类型为字符串数组），其中的值需要包含在标头中。

const OSS = require('ali-oss');

const store = new OSS({
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  bucket: 'your bucket name',
  region: 'oss-cn-hangzhou',
  authorizationV4: true ,
  stsToken: 'yourSecurityToken',
});

try {
  const bucketInfo = await store.getBucketInfo('your bucket name');
  console.log(bucketInfo);
} catch (e) {
  console.log(e);
}

try {
  const putObjectResult = await store.put('your bucket name', 'your object name', {
    headers: {
      // The headers of this request
      header1: 'value1',
      header2: 'value2',
    },
    // The keys of the request headers that need to be calculated into the V4 signature. Please ensure that these additional headers are included in the request headers.
    additionalHeaders: ['additional header1', 'additional header2'],
  });
  console.log(putObjectResult);
} catch (e) {
  console.log(e);
}