Node.js初始化

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

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

注意事项

  • 初始化OSSClient前,您需要配置访问凭证,本文以从环境变量读取访问凭证为例,详情请参见配置访问凭证

  • 关于OSS支持的RegionEndpoint的对应关系,请参见OSS地域和访问域名

  • 关于创建RAM用户的AccessKey,请参见创建AccessKey

前置条件

重要

在配置客户端前,您需要先使用RAM用户AccessKey完成配置环境变量。

  1. 创建有OSS管理权限的RAM用户AccessKey

    使用ROS脚本快速创建有OSS管理权限的RAM用户AccessKey

    在资源编排ROS控制台的创建资源栈页面的安全确认下,勾选确认,然后单击创建

    1.png

    创建完成后,在输出中,复制创建的AccessKey。

    image

  2. 使用RAM用户AccessKey配置环境变量。

    Linux

    1. 在命令行界面执行以下命令来将环境变量设置追加到~/.bashrc 文件中。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc
      1. 执行以下命令使变更生效。

        source ~/.bashrc
      2. 执行以下命令检查环境变量是否生效。

        echo $OSS_ACCESS_KEY_ID
        echo $OSS_ACCESS_KEY_SECRET

    macOS

    1. 在终端中执行以下命令,查看默认Shell类型。

      echo $SHELL
      1. 根据默认Shell类型进行操作。

        Zsh

        1. 执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。

          echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
          echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc
        2. 执行以下命令使变更生效。

          source ~/.zshrc
        3. 执行以下命令检查环境变量是否生效。

          echo $OSS_ACCESS_KEY_ID
          echo $OSS_ACCESS_KEY_SECRET

        Bash

        1. 执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。

          echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
          echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile
        2. 执行以下命令使变更生效。

          source ~/.bash_profile
        3. 执行以下命令检查环境变量是否生效。

          echo $OSS_ACCESS_KEY_ID
          echo $OSS_ACCESS_KEY_SECRET

    Windows

    CMD

    1. CMD中运行以下命令。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"
      1. 运行以下命令,检查环境变量是否生效。

        echo %OSS_ACCESS_KEY_ID%
        echo %OSS_ACCESS_KEY_SECRET%

    PowerShell

    1. PowerShell中运行以下命令。

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)
      1. 运行以下命令,检查环境变量是否生效。

        [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
        [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

  3. 参考上述方式修改系统环境变量后,请重启或刷新您的编译运行环境,包括IDE、命令行界面、其他桌面应用程序及后台服务,以确保最新的系统环境变量成功加载。

默认配置示例

以下代码示例演示了如何使用V4签名和V1签名配置OSSClient

V4签名(推荐)

重要
  • 使用V4签名算法初始化OSSClient时,您需要指定OSS专用地域ID作为发起请求地域的标识,以华东1(杭州)为例,Region填写为:oss-cn-hangzhou。如需查询其它Region ID请参见OSS地域和访问域名

  • 您需要在代码中显式声明使用 V4 签名算法,示例值:authorizationV4: true

以下是使用OSS域名配置OSSClient并使用V4签名的示例代码。

请注意,以下代码示例默认使用Bucket公网域名以及RAM用户的AK信息。

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

const client = new OSS({
  // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'oss-cn-hangzhou',
  // 使用V4签名算法
  authorizationV4: true,
  // yourBucketName填写Bucket名称。
  bucket: 'yourBucketName',
  // yourEndpoint填写Bucket所在地域对应的公网Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

V1签名(不推荐)

重要

阿里云对象存储OSS20250301日起不再对新用户(即新UID )开放使用V1签名,并将于20250901日起停止更新与维护且不再对新增Bucket开放使用V1签名。请尽快切换到V4签名,避免影响服务。更多信息,请参见公告说明

以下代码使用OSS域名配置OSSClient。关于不同地域的OSS域名,请参见OSS地域和访问域名

使用OSS域名新建Client

以下代码用于使用OSS域名初始化。

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

const client = new OSS({
  // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'yourRegion',
  // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // yourBucketName填写Bucket名称。
  bucket: 'yourBucketName',
});

使用自定义域名新建Client

以下代码用于使用自定义域名新建Client。关于使用自定义域名访问OSS的更多信息,请参见绑定自定义域名至Bucket默认域名

重要

使用自定义域名无法使用client.listBuckets()方法。

const OSS = require('ali-oss')

const client = new OSS({  
 // 使用自定义域名作为Endpoint。
 endpoint: 'http://img.example.com', 
 // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
 accessKeyId: process.env.OSS_ACCESS_KEY_ID,
 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
 cname: true,
 // yourBucketName填写Bucket名称。
 bucket: 'yourBucketName',
});

常见场景配置示例

如果您有配置其它域名的需求,请参考以下代码示例。请注意,以下代码示例默认使用V4签名以及RAM用户的AK信息。

内网域名配置示例

当您的应用部署在阿里云的ECS实例上,并且需要频繁访问同地域的OSS资源时,使用内网域名可以降低流量成本并提高访问速度。

以下是使用OSS内网域名配置OSSClient的示例代码。

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

const client = new OSS({
  // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'oss-cn-hangzhou',
  //使用V4签名
  authorizationV4: true,
  // yourBucketName填写Bucket名称。
  bucket: 'yourBucketName',
  // yourEndpoint填写Bucket所在地域对应的内网Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou-internal.aliyuncs.com。
  endpoint: 'yourEndpoint',
});

自定义域名配置示例

以下是使用自定义域名配置OSSClient的示例代码。

警告

您需要先将自定义域名绑定至Bucket默认域名,否则将引发报错!关于绑定自定义域名的详细操作,请参见绑定自定义域名至Bucket默认域名

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

const client = new OSS({
  // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'oss-cn-hangzhou',
  // 使用V4签名
  authorizationV4: true,
  // yourBucketName填写Bucket名称。
  bucket: 'yourBucketName',
  // yourEndpoint请填写您的自定义域名。例如https://static.example.com。
  endpoint: 'yourEndpoint',
  // 设置true开启CNAME选项。
  cname: true,
});

传输加速域名配置示例

以下是使用传输加速域名配置OSSClient的示例代码。

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

const client = new OSS({
  // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // yourRegion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'oss-cn-hangzhou',
  //使用V4签名
  authorizationV4: true,
  // yourBucketName填写Bucket名称。
  bucket: 'yourBucketName',
  // yourEndpoint请填写传输加速域名。例如'oss-accelerate.aliyuncs.com'
  endpoint: 'oss-accelerate.aliyuncs.com',
});

相关文档

关于OSSClient的更多配置选项,请参见官网示例