An OSSClient instance is the client of Object Storage Service (OSS) SDK for Node.js to manage OSS resources such as buckets and objects. When you use OSS SDK for Node.js to initiate an OSS request, you must initialize an OSSClient instance and modify the default configuration items based on your business requirements.
Create an OSSClient instance
(Recommended) Use the V4 signature algorithm
We recommend that you use the V4 signature algorithm which provides better security. In this case, you must declare authorizationV4. OSS SDK for Node.js 6.20.0 and later support V4 signatures.
The following sample code provides an example on how to use an OSS endpoint to create an OSSClient instance by using the V4 signature algorithm. If you want to use other methods to create an OSSClient instance by using the V4 signature algorithm, refer to the following sample code and change the variables:
const OSS = require('ali-oss');
const client = new OSS({
// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
region: 'yourRegion',
authorizationV4: true,
// Specify the name of the bucket.
bucket: 'yourBucketName',
});(Not recommended) Use the V1 signature algorithm
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.
Create an OSSClient instance by using an OSS endpoint
The following sample code provides an example on how to create an OSSClient instance by using an OSS endpoint:
const OSS = require('ali-oss');
const client = new OSS({
// Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
region: 'yourRegion',
// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// Specify the name of the bucket.
bucket: 'yourBucketName',
});Create an OSSClient instance by using a custom domain name
The following sample code provides an example on how to create an OSSClient instance by using a custom domain name. For more information, see Map a custom domain name to the default domain name of a bucket.
If you use a custom domain name, you cannot use the client.listBuckets() method.
const OSS = require('ali-oss')
const client = new OSS({
// Use a custom domain name as the endpoint of a bucket to access the bucket.
endpoint: 'http://img.example.com',
// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
cname: true,
// Specify the name of the bucket.
bucket: 'yourBucketName',
});Configure an OSSClient instance
When you initialize an OSSClient instance, you can specify configuration parameters based on your business requirements. For example, you can specify a request timeout period by specifying timeout or temporary access credentials by specifying stsToken. For more information about the supported configuration parameters and configuration examples, see Configuration parameters.