Object Storage Service:Upload a local file (Node.js SDK)

Prerequisites

Before you begin, ensure that you have:

• An OSS bucket

• The oss:PutObject permission granted to your RAM user or RAM role via a RAM policy or bucket policy

• (Conditional) The oss:PutObjectTagging permission, if you upload with the x-oss-tagging header

• (Conditional) The kms:GenerateDataKey and kms:Decrypt permissions, if the object metadata includes X-Oss-Server-Side-Encryption: KMS

Alibaba Cloud accounts have full permissions by default. RAM users and RAM roles have no permissions by default.

Usage notes

• If an object with the same key already exists in the bucket, put overwrites it. Set x-oss-forbid-overwrite to true to prevent this.

• The object key cannot include the bucket name.

• If the local file path has no directory component, OSS uploads the file from the directory where the project runs.

Permissions

Sample code

The following example uploads D:\localpath\examplefile.txt to examplebucket as an object named exampleobject.txt. Required parameters are marked /* Required */. The optional headers show available customization — remove any that don't apply.

Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET as environment variables before running the code.

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

// Initialize the OSS client.
// Store your AccessKey ID and AccessKey secret in environment variables
// to avoid hardcoding credentials in source code.
const client = new OSS({
  region: 'yourregion',                             /* Required — e.g., oss-cn-hangzhou */
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,       /* Required */
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET, /* Required */
  authorizationV4: true,
  bucket: 'examplebucket',                          /* Required */
});

// Optional headers — remove any that do not apply to your use case.
const headers = {
  // Storage class of the object.
  'x-oss-storage-class': 'Standard',
  // Object ACL. Defaults to inheriting the bucket ACL if omitted.
  'x-oss-object-acl': 'private',
  // Serve the object as a downloadable attachment when accessed by URL.
  'Content-Disposition': 'attachment; filename="example.txt"',
  // Object tags. Requires the oss:PutObjectTagging permission.
  'x-oss-tagging': 'Tag1=1&Tag2=2',
  // Prevent overwriting an existing object with the same key.
  'x-oss-forbid-overwrite': 'true',
};

async function put() {
  try {
    // First argument: object key (cannot contain the bucket name).
    // Second argument: local file path.
    const result = await client.put(
      'exampleobject.txt',                               /* Required */
      path.normalize('D:\\localpath\\examplefile.txt'), /* Required */
      { headers }
    );
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

put();

Replace the following placeholders before running the code:

FAQ

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'examplebucket',
  secure: true, // Forces HTTPS for generated URLs
});

What's next

• For more Node.js upload examples, see GitHub examples.

• For the complete API reference, see PutObject.