Initialize the Node.js SDK to connect to OSS - Object Storage Service

The Client is the primary object for interacting with Object Storage Service (OSS) through the Node.js software development kit (SDK). It manages OSS resources, such as buckets and files. To send OSS requests using the Node.js SDK, initialize a Client instance and modify the default configurations as needed.

Notes

You must configure access credentials before you initialize an OSSClient instance. This topic provides an example of using environment variables. For more information, see Configure access credentials (Node.js SDK).
For information about OSS regions and their corresponding endpoints, see Regions and endpoints.
For information about how to create an AccessKey pair for a Resource Access Management (RAM) user, see Create an AccessKey pair.

Prerequisites

Important

Before you configure the client, you must set the environment variables using the AccessKey of a RAM user.

Create an AccessKey for a RAM user that has OSS management permissions.
You can use a Resource Orchestration Service (ROS) script to quickly create an AccessKey for a RAM user that has OSS management permissions.
On the Create Stack page, under Security Confirmation, select the confirmation checkbox, and then click Create.
After the stack is created, copy the AccessKey from the Outputs tab.

Set the environment variables using the AccessKey of the RAM user.

Linux

In the command-line interface, run the following commands to append the environment variable settings to the ~/.bashrc file.
```
echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc
```
1. Run the following command to apply the changes.
```
source ~/.bashrc
```
2. Run the following commands to verify that the environment variables are set.
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

macOS

In the terminal, run the following command to view the default shell type.
```
echo $SHELL
```
1. Follow the steps for your default shell type.
  Zsh
  1. Run the following commands to append the environment variable settings to the ~/.zshrc file.
    echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc
  2. Run the following command to apply the changes.
    source ~/.zshrc
  3. Run the following commands to verify that the environment variables are set.
    echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
  Bash
  1. Run the following commands to append the environment variable settings to the ~/.bash_profile file.
    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. Run the following command to apply the changes.
    source ~/.bash_profile
  3. Run the following commands to verify that the environment variables are set.
    echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET

Windows

CMD

Run the following commands in Command Prompt.

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

Run the following commands to verify that the environment variables are set.
```
echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%
```

PowerShell

Run the following commands in 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)

Run the following commands to verify that the environment variables are set.

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

After you modify the system environment variables, you must restart or refresh your development environment. This includes your IDE, command-line interface, desktop applications, and background services. This ensures that the latest system environment variables are loaded.

Default configuration examples

The following code examples show how to configure an OSSClient instance using Signature V4 and Signature V1.

Signature V4 (recommended)

Important

When you initialize an OSSClient instance with the Signature V4 algorithm, specify the OSS-specific region ID. This ID identifies the region to which the request is sent. For example, for the China (Hangzhou) region, set the Region to oss-cn-hangzhou. For other region IDs, see Regions and endpoints.
In your code, you must explicitly declare the use of the Signature V4 algorithm. For example: authorizationV4: true.

The following code provides an example of how to configure an OSSClient instance using an OSS domain name and Signature V4.

By default, the following code example uses the public domain name of the bucket and the AccessKey information of a RAM user.

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

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use the Signature V4 algorithm.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to the public endpoint of the region where the bucket is located. For example, for China (Hangzhou), set endpoint to https://oss-cn-hangzhou.aliyuncs.com.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

Signature V1 (not recommended)

Important

From March 1, 2025, the V1 signature algorithm of OSS is no longer available to new customers with new UIDs. From September 1, 2025, OSS no longer updates and maintains the V1 signature algorithm, and the V1 signature algorithm is no longer available for new buckets. Upgrade V1 signatures to V4 signatures at the earliest opportunity to prevent impact on your business.

The following code configures an OSSClient instance using an OSS domain name. For information about OSS domain names for different regions, see Regions and endpoints.

Create a Client instance using an OSS domain name

The following code shows how to initialize an instance using an OSS domain name.

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

const client = new OSS({
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'yourRegion',
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
});

Create a Client instance using a custom domain name

The following code shows how to create a Client instance using a custom domain name. For more information about accessing OSS using a custom domain name, see Access OSS using a custom domain name.

Important

You cannot use the client.listBuckets() method if you use a custom domain name.

const OSS = require('ali-oss')

const client = new OSS({  
 // Use a custom domain name as the endpoint.
 endpoint: 'http://img.example.com', 
 // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
 accessKeyId: process.env.OSS_ACCESS_KEY_ID,
 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
 cname: true,
 // Set bucket to the name of your bucket.
 bucket: 'yourBucketName',
});

Configuration examples for common scenarios

The following code examples show how to configure other domain names. By default, these examples use Signature V4 and the AccessKey information of a RAM user.

Internal domain name configuration example

If your application is deployed on an Alibaba Cloud ECS instance and needs to frequently access OSS resources in the same region, you can use an internal domain name to reduce traffic costs and improve access speed.

The following code shows an example of how to configure an OSSClient instance using an OSS internal domain name.

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

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  //Use Signature V4.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to the internal endpoint of the region where the bucket is located. For example, for China (Hangzhou), set endpoint to https://oss-cn-hangzhou-internal.aliyuncs.com.
  endpoint: 'yourEndpoint',
});

Custom domain name configuration example

The following code shows an example of how to configure an OSSClient instance using a custom domain name.

Warning

You must first attach the custom domain name to the default domain name of the bucket. Otherwise, an error occurs. For more information about how to attach a custom domain name, see Access OSS using a custom domain name.

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

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use the Signature V4 algorithm.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to your custom domain name. For example, https://static.example.com.
  endpoint: 'yourEndpoint',
  // Set cname to true to enable the CNAME option.
  cname: true,
});

Acceleration endpoint configuration example

The following code shows an example of how to configure an OSSClient instance using an acceleration endpoint.

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

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  //Use Signature V4.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to an acceleration endpoint. For example, oss-accelerate.aliyuncs.com.
  endpoint: 'oss-accelerate.aliyuncs.com',
});

References

For more information about OSSClient configuration options, see Examples on GitHub.

Notes

Prerequisites

Linux

macOS

Zsh

Bash

Windows

CMD

PowerShell

Default configuration examples

Signature V4 (recommended)

Signature V1 (not recommended)

Create a Client instance using an OSS domain name

Create a Client instance using a custom domain name

Configuration examples for common scenarios

Internal domain name configuration example

Custom domain name configuration example

Acceleration endpoint configuration example

References