`ali-oss` is the official Node.js client library for Alibaba Cloud Object Storage Service (OSS). It provides a comprehensive, promise-based API for interacting with OSS buckets and objects, covering essential operations like uploading, downloading, listing, and managing object access. The current stable version is `6.23.0`, released on May 15, 2025. The library maintains a regular release cadence, with minor versions frequently introducing new features, bug fixes, and performance enhancements. Key differentiators include direct support for Alibaba Cloud-specific features such as CloudBox, V4 signatures, and detailed bucket/object lifecycle management, making it an essential tool for applications integrating with Alibaba Cloud infrastructure. It supports Node.js environments from version 8 and above, and also offers limited browser compatibility for certain operations.
npm install ali-ossVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates basic `ali-oss` operations: client initialization, uploading a local file, downloading it, listing objects in a bucket, retrieving object metadata, and finally deleting the uploaded file. It uses environment variables for secure credential handling.
Review your object naming conventions and ensure they strictly comply with Alibaba Cloud OSS object naming rules. If encountering issues, consult OSS documentation for valid object name characters. While possible to disable strict verification, it's not recommended for security reasons.
For files exceeding a few megabytes, always use `client.multipartUpload(objectName, filePath, options)` to leverage chunking, parallel uploads, and resumable transfer capabilities for better performance and reliability.
For new deployments and enhanced security, ensure your OSS client and bucket configuration (if applicable) are set to utilize Signature V4. For CloudBox access, configure the `endpoint` and `authorizationV4: true` option as specified in the documentation.
Thoroughly double-check your `region` (e.g., 'oss-cn-hangzhou'), `accessKeyId`, and `accessKeySecret` against your Alibaba Cloud console. Ensure the IAM user associated with the `accessKeyId` has the necessary permissions for the bucket and intended operations. Verify the bucket exists in the specified region.
Verify the bucket name for typos and confirm the `region` in your OSS client configuration precisely matches the actual region where your bucket is located. Confirm the bucket exists and is accessible in your Alibaba Cloud console.
Review the IAM user's policies linked to your `accessKeyId` or the bucket's ACLs and policies. Grant the necessary `oss:PutObject`, `oss:GetObject`, `oss:DeleteObject`, etc., permissions for the bucket and objects involved in your operations.
Ensure the `region` in your client configuration is accurate (e.g., `oss-cn-hangzhou`). Check your local network, proxy settings, and firewall rules to ensure outbound connections to the OSS endpoint are allowed. Verify DNS resolution for the OSS domain for your region.
Rename your bucket to comply with OSS naming rules: bucket names must be 3 to 63 characters long, consist only of lowercase letters, numbers, and hyphens (`-`), and must start and end with a letter or number.
No dependency data recorded yet.