{"id":15747,"library":"oss-client","title":"Aliyun OSS Node.js Client","description":"The `oss-client` package provides a robust Node.js client for Alibaba Cloud's Object Storage Service (OSS), functionally similar to Amazon S3. The current stable version is 2.5.1, released in August 2025. This library maintains an active release cadence, with minor feature updates every few months and bug fixes as needed. It leverages modern JavaScript features, exclusively using `async/await` for all operations, making asynchronous programming straightforward. A key differentiator is its strong TypeScript support and ESM-first approach since version 2.0.0, catering to contemporary Node.js development practices. It is specifically designed for Aliyun OSS, offering comprehensive object manipulation capabilities including put, get, delete, stream handling, URL generation, and ACL management, along with support for bucket and object tagging.","status":"active","version":"2.5.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/node-modules/oss-client","tags":["javascript","oss","client","file","aliyun","typescript"],"install":[{"cmd":"npm install oss-client","lang":"bash","label":"npm"},{"cmd":"yarn add oss-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add oss-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"HTTP client for network requests to OSS. Version 4.x is required since oss-client v2.4.0.","package":"urllib","optional":false}],"imports":[{"note":"Since v2.0.0, oss-client is primarily ESM-first. While CommonJS `require` might work with transpilation, direct ESM import is recommended. For Node.js < 16, use v1.x.","wrong":"const { OSSObject } = require('oss-client');","symbol":"OSSObject","correct":"import { OSSObject } from 'oss-client';"},{"note":"Importing types like `ClientOptions` is crucial for TypeScript projects to leverage static analysis and auto-completion for client configuration.","symbol":"ClientOptions","correct":"import type { ClientOptions } from 'oss-client';"},{"note":"Importing specific operation options types, such as `PutObjectOptions`, helps ensure correct parameter usage for methods like `put` and `putStream` in TypeScript.","symbol":"PutObjectOptions","correct":"import type { PutObjectOptions } from 'oss-client';"}],"quickstart":{"code":"import { OSSObject } from 'oss-client';\nimport { readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\nconst ossObject = new OSSObject({\n  region: process.env.OSS_REGION ?? 'oss-cn-hangzhou',\n  endpoint: process.env.OSS_ENDPOINT ?? 'https://oss-cn-hangzhou.aliyuncs.com',\n  accessKeyId: process.env.OSS_ACCESS_KEY_ID ?? 'YOUR_ACCESS_KEY_ID',\n  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET ?? 'YOUR_ACCESS_KEY_SECRET',\n  bucket: process.env.OSS_BUCKET_NAME ?? 'your-bucket-name',\n});\n\nasync function uploadFile() {\n  const localFilePath = join(__dirname, 'test-file.txt');\n  // For demonstration, create a dummy file if it doesn't exist\n  try {\n    readFileSync(localFilePath);\n  } catch (error) {\n    require('node:fs').writeFileSync(localFilePath, 'Hello, Aliyun OSS!');\n  }\n\n  const remoteObjectName = 'my-test-object.txt';\n  try {\n    const result = await ossObject.put(remoteObjectName, localFilePath);\n    console.log(`Successfully uploaded: ${result.name} to ${result.url}`);\n\n    const downloadResult = await ossObject.get(remoteObjectName);\n    console.log(`Downloaded content: ${downloadResult.content?.toString()}`);\n\n    await ossObject.delete(remoteObjectName);\n    console.log(`Successfully deleted: ${remoteObjectName}`);\n  } catch (error) {\n    console.error('OSS operation failed:', error);\n  }\n}\n\nuploadFile();","lang":"typescript","description":"Demonstrates initializing the OSS client, uploading a file, retrieving its content, and then deleting the object using async/await."},"warnings":[{"fix":"Upgrade Node.js to version 16.0.0 or higher, or pin `oss-client` to version `1.x`.","message":"Version 2.0.0 introduced significant breaking changes, dropping support for Node.js versions below 16.0.0. Projects on older Node.js versions must either upgrade Node.js or remain on `oss-client` v1.x.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Refactor code to remove usage of `stsToken`, `headerEncoding`, and `Bucket`/`Image Client` specific APIs. Consult Aliyun OSS documentation for alternative approaches for STS or image processing.","message":"With v2.0.0, support for `stsToken`, `headerEncoding`, and dedicated `Bucket` and `Image Client` APIs was removed. These functionalities require alternative implementations or SDKs.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `urllib` is compatible with your project's ecosystem. Review `urllib` v4.x release notes for any breaking changes that might affect your direct `urllib` usage, if any.","message":"The `urllib` dependency was upgraded to version 4.x in `oss-client` v2.4.0. This might introduce breaking changes in `urllib` itself if your project directly or indirectly relied on older `urllib` versions.","severity":"breaking","affected_versions":">=2.4.0"},{"fix":"Replace all calls to `client.getObjectUrl(name)` with `client.generateObjectUrl(name)`.","message":"The `getObjectUrl` method was deprecated in favor of `generateObjectUrl` in v2.0.1. While `getObjectUrl` still exists as an alias, using the new method is recommended for future compatibility.","severity":"gotcha","affected_versions":">=2.0.1"},{"fix":"Always handle stream errors and ensure streams are properly piped or consumed and closed. Consider using `pipeline` from `node:stream/promises` for robust stream handling.","message":"When using `putStream`, ensure the stream is correctly handled and closed. Improper stream management can lead to resource leaks or incomplete uploads, especially with large files.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) and use `import { OSSObject } from 'oss-client';`. Alternatively, for older Node.js or strict CommonJS environments, consider `oss-client` v1.x.","cause":"Attempting to use `require()` to import `oss-client` in a CommonJS context when the package is primarily designed for ESM in v2.x.","error":"ERR_REQUIRE_ESM: require() of ES Module ... oss-client/index.js from ... not supported."},{"fix":"Verify that `new OSSObject({...})` is correctly called and that `OSSObject` is properly imported. Check the method signature and available methods against the documentation for your `oss-client` version.","cause":"Incorrectly instantiating the `OSSObject` client or trying to call a method that doesn't exist or is not exposed.","error":"TypeError: ossObject.put is not a function"},{"fix":"Double-check your `accessKeyId`, `accessKeySecret`, `region`, and `bucket` configurations for typos. Ensure the keys have the necessary permissions for the operations being performed. If using temporary credentials, verify their validity.","cause":"Authentication failure due to incorrect `accessKeyId`, `accessKeySecret`, or an expired `stsToken` (if using v1.x or a custom STS solution). This can also happen if the region or bucket name is wrong.","error":"Error: signature is invalid"}],"ecosystem":"npm"}