AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 对象存储 开发参考 SDK参考 OSS Node.js SDK 初始化

Node.js初始化

更新时间：
产品详情
我的收藏
重要

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

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

注意事项

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

  • 关于OSS支持的Region与Endpoint的对应关系，请参见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签名（不推荐）

重要

阿里云对象存储OSS自2025年03月01日起不再对新用户（即新UID ）开放使用V1签名，并将于2025年09月01日起停止更新与维护且不再对新增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的更多配置选项，请参见官网示例。

上一篇：安装下一篇：快速入门