為Node.js應用提供簡單易用的OSS整合方案，支援檔案上傳下載、許可權管理等核心功能，快速實現雲端檔案儲存體和管理能力。
快速接入
通過以下步驟快速接入OSS Node.js SDK。
準備環境
下載並安裝Node.js運行環境。建議使用Node.js 8.0及以上版本以獲得更好的相容性和效能表現。
執行
node -v命令查看Node.js版本。執行
npm -v命令查看npm版本。
安裝SDK
根據Node.js版本選擇對應的SDK版本。
Node.js 8.0及以上版本：使用最新的SDK 6.x版本。
Node.js 8.0以下版本：使用SDK 4.x版本。
安裝6.x版本（推薦）
npm install ali-oss@^6.x --save安裝4.x版本
npm install ali-oss@^4.x --save安裝完成後，執行npm list ali-oss命令驗證SDK是否成功安裝，成功時會顯示對應的SDK版本資訊。
配置訪問憑證
使用 RAM 使用者的 AccessKey 配置訪問憑證。
在 RAM 控制台，建立使用永久 AccessKey 訪問的 RAM 使用者，儲存 AccessKey，然後為該使用者授予
AliyunOSSFullAccess許可權。使用 RAM 使用者的 AccessKey 配置環境變數。
Linux
在命令列介面執行以下命令，將環境變數設定追加到
~/.bashrc檔案中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc執行以下命令使變更生效。
source ~/.bashrc執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
macOS
在終端中執行以下命令，查看預設Shell類型。
echo $SHELL根據預設Shell類型進行操作。
Zsh
執行以下命令，將環境變數設定追加到
~/.zshrc檔案中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc執行以下命令使變更生效。
source ~/.zshrc執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
Bash
執行以下命令，將環境變數設定追加到
~/.bash_profile檔案中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile執行以下命令使變更生效。
source ~/.bash_profile執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
Windows
CMD
在CMD中運行以下命令。
setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID" setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"運行以下命令，檢查環境變數是否生效。
echo %OSS_ACCESS_KEY_ID% echo %OSS_ACCESS_KEY_SECRET%
PowerShell
在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)運行以下命令，檢查環境變數是否生效。
[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User) [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)
初始化用戶端
運行範例程式碼前，請將代碼中的<region-id>預留位置替換為實際的地區和Endpoint，如ap-southeast-1。
// OSS Node.js SDK初始化用戶端樣本
const OSS = require('ali-oss');
async function main() {
// 從環境變數中擷取訪問憑證（需要設定OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
const client = new OSS({
// 填寫Bucket所在地區
region: 'oss-<region-id>',
// 從環境變數中擷取訪問憑證
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// 啟用V4簽名
authorizationV4: true,
});
try {
// 列舉所有Bucket
const result = await client.listBuckets();
// 輸出Bucket列表資訊
console.log(`共找到 ${result.buckets.length} 個Bucket:`);
for (const bucket of result.buckets) {
console.log(bucket.name);
}
} catch (err) {
console.log('列舉Bucket失敗，詳細資料如下:');
console.error(err);
return;
}
}
// 執行主函數
main().catch(console.error);
用戶端配置
OSS用戶端支援多種配置選項以適應不同的網路環境和效能需求。通過自訂Endpoint類型、設定逾時時間和串連數等配置參數，可以最佳化用戶端的訪問效能和穩定性。完整配置選項詳見用戶端配置項。
使用內網網域名稱
通過內網網域名稱訪問OSS可以避免公網流量費用，同時獲得更高的訪問速度和安全性。初始化用戶端時將Endpoint設定為內網訪問網域名稱即可啟用內網訪問。
運行範例程式碼前，請將代碼中的<region-id>等預留位置替換為實際的地區和Endpoint，如ap-southeast-1。
const client = new OSS({
region: 'oss-<region-id>',
// 從環境變數中擷取訪問憑證
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// 啟用V4簽名
authorizationV4: true,
// 使用內網訪問網域名稱
endpoint: '<endpoint>',
});使用自訂網域名
將Endpoint指定為自訂網域名，並在初始化用戶端時通過cname: true參數啟用CNAME選項，即可實現自訂網域名訪問。
使用前需確保已將自訂網域名綁定到Bucket。詳見通過自訂網域名訪問OSS。
使用自訂網域名時無法調用client.listBuckets()方法。
運行範例程式碼前，請將代碼中的<region-id>預留位置替換為實際的地區和Endpoint，如ap-southeast-1。
// 從環境變數中擷取訪問憑證（需要設定OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
const client = new OSS({
region: 'oss-<region-id>',
// 從環境變數中擷取訪問憑證
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// 啟用V4簽名
authorizationV4: true,
// 使用自訂網域名
endpoint: 'http://example.com',
// 填寫Bucket名稱，Bucket名稱必須和自訂網域名綁定
bucket: 'example-bucket',
// 開啟CNAME選項
cname: true,
});使用傳輸加速網域名稱
初始化OSS用戶端時，將Endpoint指定為傳輸加速網域名稱即可實現加速訪問。
運行範例程式碼前，請將代碼中的<region-id>預留位置替換為實際的地區和Endpoint，如ap-southeast-1。
// 從環境變數中擷取訪問憑證（需要設定OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
const client = new OSS({
region: 'oss-<region-id>',
// 從環境變數中擷取訪問憑證
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// 啟用V4簽名
authorizationV4: true,
// 使用傳輸加速網域名稱
endpoint: 'https://oss-accelerate.aliyuncs.com',
// 填寫Bucket名稱，Bucket必須開啟傳輸加速功能
bucket: 'example-bucket',
});簽名版本
阿里雲Object Storage Service V1 簽名將按以下時間錶停止使用，建議儘快升級為V4簽名，確保服務不受影響。
自 2025 年 3 月 1 日起，新註冊使用者無法使用 V1 簽名。
自 2025 年 9 月 1 日起，逐步停止 V1 簽名的更新維護，且新建立的 Bucket 無法使用 V1 簽名。
以下範例程式碼採用V1簽名初始化用戶端。V4簽名用戶端初始化範例程式碼參見初始化用戶端。
// OSS Node.js SDK初始化用戶端樣本
const OSS = require('ali-oss');
async function main() {
// 從環境變數中擷取訪問憑證（需要設定OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
const client = new OSS({
// 從環境變數中擷取訪問憑證
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
});
try {
// 列舉所有Bucket
const result = await client.listBuckets();
// 輸出Bucket列表資訊
console.log(`共找到 ${result.buckets.length} 個Bucket:`);
for (const bucket of result.buckets) {
console.log(bucket.name);
}
} catch (err) {
console.log('列舉Bucket失敗，詳細資料如下:');
console.error(err);
return;
}
}
// 執行主函數
main().catch(console.error);
範例程式碼
以下提供檔案基本操作的範例程式碼，涵蓋上傳、下載、刪除和列舉檔案等核心功能。通過這些樣本可以快速掌握OSS Node.js SDK的基本用法，更多完整樣本請參見Github樣本或具體功能SDK參考文檔。
上傳檔案
以下樣本示範如何將本地檔案上傳至OSS Bucket，同時展示如何通過自訂要求標頭設定檔案屬性，實現儲存類型、存取權限、標籤等精細化控制。
運行範例程式碼前，請將代碼中的<region-id>預留位置替換為實際的地區和Endpoint，如ap-southeast-1。
// OSS Node.js SDK上傳檔案樣本
const OSS = require('ali-oss');
const path = require('path');
async function main() {
// 從環境變數中擷取訪問憑證（需要設定OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
const client = new OSS({
region: 'oss-<region-id>',
// 從環境變數中擷取訪問憑證
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// 啟用V4簽名
authorizationV4: true,
// 填寫Bucket名稱
bucket: 'example-bucket',
});
// 自訂要求標頭
const headers = {
// 指定Object的儲存類型
'x-oss-storage-class': 'Standard',
// 指定Object的存取權限
'x-oss-object-acl': 'private',
// 通過檔案URL訪問檔案時，指定以附件形式下載檔案
'Content-Disposition': 'attachment',
// 設定Object的標籤，可同時設定多個標籤
'x-oss-tagging': 'Tag1=1&Tag2=2',
// 指定PutObject操作時是否覆蓋同名目標Object。此處設定為true，表示禁止覆蓋同名Object
'x-oss-forbid-overwrite': 'true',
};
try {
// 設定檔資訊
const key = 'dest.jpg'; // OSS中的檔案路徑
const localFilePath = path.normalize('dest.jpg'); // 本地檔案的完整路徑
// 將本地檔案上傳到OSS指定路徑
const result = await client.put(key, localFilePath, { headers });
console.log(`檔案上傳完成: ${localFilePath} -> ${key}`);
console.log('上傳結果:', result);
} catch (err) {
console.log('上傳失敗，詳細資料如下:');
console.error(err);
return;
}
}
// 執行主函數
main().catch(console.error);
下載檔案
以下樣本示範如何從OSS Bucket下載檔案至本地指定路徑。
運行範例程式碼前，請將代碼中的<region-id>預留位置替換為實際的地區和Endpoint，如ap-southeast-1。
// OSS Node.js SDK下載檔案樣本
const OSS = require('ali-oss');
async function main() {
// 從環境變數中擷取訪問憑證（需要設定OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
const client = new OSS({
region: 'oss-<region-id>',
// 從環境變數中擷取訪問憑證
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// 啟用V4簽名
authorizationV4: true,
// 填寫Bucket名稱
bucket: 'example-bucket',
});
try {
// 設定檔資訊
const key = 'dest.jpg'; // OSS中的檔案路徑
const filePath = 'dest.jpg'; // 本地儲存路徑
// 將OSS中的檔案下載到本地指定路徑
const result = await client.get(key, filePath);
console.log(`檔案下載完成: ${key} -> ${filePath}`);
} catch (err) {
console.log('下載失敗，詳細資料如下:');
console.error(err);
return;
}
}
// 執行主函數
main().catch(console.error);
刪除檔案
以下樣本示範如何刪除OSS Bucket中的指定檔案。
運行範例程式碼前，請將代碼中的<region-id>預留位置替換為實際的地區和Endpoint，如ap-southeast-1。
// OSS Node.js SDK刪除檔案樣本
const OSS = require('ali-oss');
async function main() {
// 從環境變數中擷取訪問憑證（需要設定OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
const client = new OSS({
region: 'oss-<region-id>',
// 從環境變數中擷取訪問憑證
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// 啟用V4簽名
authorizationV4: true,
// 填寫Bucket名稱
bucket: 'example-bucket',
});
try {
// 設定檔資訊
const key = 'dest.jpg'; // OSS中要刪除的檔案路徑
// 刪除OSS中的指定檔案
const result = await client.delete(key);
console.log(`檔案刪除完成: ${key}`);
console.log('刪除結果:', result);
} catch (err) {
console.log('刪除失敗，詳細資料如下:');
console.error(err);
return;
}
}
// 執行主函數
main().catch(console.error);
列舉檔案
以下樣本示範如何列舉OSS Bucket中的檔案，預設返回最多100個檔案的詳細資料。
運行範例程式碼前，請將代碼中的<region-id>預留位置替換為實際的地區和Endpoint，如ap-southeast-1。
// OSS Node.js SDK列舉檔案樣本
const OSS = require('ali-oss');
async function main() {
// 從環境變數中擷取訪問憑證（需要設定OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
const client = new OSS({
region: 'oss-<region-id>',
// 從環境變數中擷取訪問憑證
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// 啟用V4簽名
authorizationV4: true,
// 填寫Bucket名稱
bucket: 'example-bucket',
});
try {
// 不帶任何參數，預設最多返回100個檔案
const result = await client.list();
console.log(`共找到 ${result.objects ? result.objects.length : 0} 個檔案:`);
// 輸出檔案列表資訊
if (result.objects && result.objects.length > 0) {
for (const object of result.objects) {
console.log(`檔案名稱: ${object.name}, 大小: ${object.size} bytes, 修改時間: ${object.lastModified}`);
}
} else {
console.log('Bucket中沒有找到任何檔案');
}
} catch (err) {
console.log('列舉檔案失敗，詳細資料如下:');
console.error(err);
return;
}
}
// 執行主函數
main().catch(console.error);
異常處理
使用OSS Node.js SDK訪問OSS時出現錯誤，OSS會返回包含HTTP狀態代碼、錯誤訊息、請求ID等詳細資料的錯誤響應。例如下載不存在的對象檔案時，會返回以下錯誤資訊（省略了部分資訊）：
Error [NoSuchKeyError]: Object not exists {
status: 404,
code: 'NoSuchKey',
requestId: '6904202CA7BABC37395E28AB'
}通過錯誤碼尋找相應錯誤原因和解決方案，完整的錯誤碼資訊請參見HTTP錯誤碼。遇到問題時也可根據requestId尋求線上支援人員的協助。
訪問憑證配置
OSS 支援多種憑證初始化方式，需根據認證和授權需求選擇合適的初始化方式。
使用RAM使用者的AK
適用於應用程式部署運行在安全、穩定且不易受外部攻擊的環境中，需要長期訪問OSS且無法頻繁輪轉憑證的情境。通過阿里雲主帳號或RAM使用者的AK（Access Key ID、Access Key Secret）初始化憑證提供者。該方式需要手動維護AK，存在安全性風險和維護複雜度增加的風險。
阿里雲帳號擁有資源的全部許可權，AK一旦泄露，會給系統帶來巨大風險，不建議使用。推薦使用最小化授權的RAM使用者的AK。
如需建立RAM使用者的AK，請直接存取建立AccessKey。RAM使用者的Access Key ID、Access Key Secret資訊僅在建立時顯示，如若遺忘請建立新的AK進行替換。
使用RAM使用者AccessKey配置環境變數。
Linux
在命令列介面執行以下命令，將環境變數設定追加到
~/.bashrc檔案中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc執行以下命令使變更生效。
source ~/.bashrc執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
macOS
在終端中執行以下命令，查看預設Shell類型。
echo $SHELL根據預設Shell類型進行操作。
Zsh
執行以下命令，將環境變數設定追加到
~/.zshrc檔案中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc執行以下命令使變更生效。
source ~/.zshrc執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
Bash
執行以下命令，將環境變數設定追加到
~/.bash_profile檔案中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile執行以下命令使變更生效。
source ~/.bash_profile執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
Windows
CMD
在CMD中運行以下命令。
setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID" setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"運行以下命令，檢查環境變數是否生效。
echo %OSS_ACCESS_KEY_ID% echo %OSS_ACCESS_KEY_SECRET%
PowerShell
在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)運行以下命令，檢查環境變數是否生效。
[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User) [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)
參考上述方式修改系統內容變數後，需重啟或重新整理編譯運行環境，包括IDE、命令列介面、其他傳統型應用程式及後台服務，以確保最新的系統內容變數成功載入。
使用環境變數傳遞憑證資訊。
const OSS = require("ali-oss"); // 初始化OSS const client = new OSS({ // 從環境變數中擷取AccessKey ID的值 accessKeyId: process.env.OSS_ACCESS_KEY_ID, // 從環境變數中擷取AccessKey Secret的值 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET }); // listBuckets const buckets = await client.listBuckets(); console.log(buckets);
使用STS臨時訪問憑證
適用於應用程式需要臨時訪問OSS的情境。通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token）初始化憑證提供者。該方式需要手動維護STS Token，存在安全性風險和維護複雜度增加的風險。如果需要多次臨時訪問OSS，需要手動重新整理STS Token。
通過OpenAPI方式簡單快速擷取STS臨時訪問憑證，請參見AssumeRole - 擷取扮演角色的臨時身份憑證。
通過SDK方式擷取STS臨時訪問憑證，請參見使用STS臨時訪問憑證訪問OSS。
請注意，STS Token在產生的時候需要指定到期時間，到期後自動失效不能再使用。
擷取關於STS服務的存取點列表，請參見服務存取點。
使用臨時身份憑證設定環境變數。
Mac OS/Linux/Unix
重要請注意，此處使用的是通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token），而非RAM使用者的Access Key和Access Key Secret。
請注意區分STS服務擷取的Access Key ID以STS開頭，例如“STS.****************”。
export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID> export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET> export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>Windows
重要請注意，此處使用的是通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token），而非RAM使用者的AK（Access Key ID、Access Key Secret）。
請注意區分STS服務擷取的Access Key ID以STS開頭，例如“STS.****************”。
set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID> set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET> set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>通過環境變數傳遞憑證資訊。
const OSS = require("ali-oss"); // 初始化OSS const client = new OSS({ // 從環境變數中擷取AccessKey ID的值 accessKeyId: process.env.OSS_ACCESS_KEY_ID, // 從環境變數中擷取AccessKey Secret的值 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET, // 從環境變數中擷取STS Token的值 stsToken: process.env.OSS_SESSION_TOKEN }); // listBuckets const buckets = await client.listBuckets(); console.log(buckets);
使用RAMRoleARN
適用於應用程式需要授權訪問OSS，例如跨阿里雲帳號訪問OSS的情境。通過指定RAM角色的ARN（Alibabacloud Resource Name）初始化憑證提供者，底層實現基於STS Token。Credentials工具會前往STS服務擷取STS Token，並在會話到期前調用AssumeRole介面申請新的STS Token。還可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。
阿里雲帳號擁有資源的全部許可權，AK一旦泄露，會給系統帶來巨大風險，不建議使用。推薦使用最小化授權的RAM使用者的AK。
如需建立RAM使用者的AK，請直接存取建立AccessKey。RAM使用者的Access Key ID、Access Key Secret資訊僅在建立時顯示，請及時儲存，如若遺忘請建立新的AK進行輪換。
如需擷取RAMRoleARN，請直接存取建立角色。
添加credentials依賴。
npm install @alicloud/credentials配置AK和RAMRoleARN作為訪問憑證。
const Credential = require("@alicloud/credentials"); const OSS = require("ali-oss"); // 使用RamRoleArn初始化Credentials Client。 const credentialsConfig = new Credential.Config({ // 憑證類型。 type: "ram_role_arn", // 從環境變數中擷取AccessKey ID的值 accessKeyId: process.env.OSS_ACCESS_KEY_ID, // 從環境變數中擷取AccessKey Secret的值 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET, // 要扮演的RAM角色ARN，樣本值：acs:ram::123456789012****:role/adminrole，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定roleArn roleArn: '<RoleArn>', // 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定RoleSessionName roleSessionName: '<RoleSessionName>', // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"} // policy: '<Policy>', roleSessionExpiration: 3600 }); const credentialClient = new Credential.default(credentialsConfig); const credential = await credentialClient.getCredential(); // 初始化OSS const client = new OSS({ accessKeyId:credential.accessKeyId, accessKeySecret: credential.accessKeySecret, stsToken: credential.securityToken, refreshSTSTokenInterval: 0, // 由Credential控制accessKeyId、accessKeySecret和stsToken值的更新 refreshSTSToken: async () => { const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential(); return { accessKeyId, accessKeySecret, stsToken: securityToken, }; } }); // listBuckets const buckets = await client.listBuckets(); console.log( buckets);
使用ECSRAMRole
適用於應用程式運行在ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中的情境。建議使用ECSRAMRole初始化憑證提供者，底層實現基於STS Token。ECSRAMRole允許將一個角色關聯到ECS執行個體、ECI執行個體或Container Service Kubernetes 版的Worker節點，實現在執行個體內部自動重新整理STS Token。該方式無需提供AK或STS Token，消除了手動維護AK或STS Token的風險。如何擷取ECSRAMRole，請參見建立角色。如何將一個角色關聯到ECS執行個體，請參見執行個體RAM角色。
添加credentials依賴。
npm install @alicloud/credentials配置ECSRAMRole作為訪問憑證。
const Credential = require("@alicloud/credentials"); const OSS = require("ali-oss"); // 使用RamRoleArn初始化Credentials Client。 const credentialsConfig = new Credential.Config({ // 憑證類型。 type: "ecs_ram_role", // 選填，該ECS角色的角色名稱，不填會自動擷取，但是建議加上以減少請求次數，可以通過環境變數ALIBABA_CLOUD_ECS_METADATA設定roleName roleName: '<RoleName>' }); const credentialClient = new Credential.default(credentialsConfig); const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential(); // 初始化OSS Client const client = new OSS({ accessKeyId, accessKeySecret, stsToken: securityToken, refreshSTSTokenInterval: 0, // 由Credential控制accessKeyId、accessKeySecret和stsToken值的更新 refreshSTSToken: async () => { const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential(); return { accessKeyId, accessKeySecret, stsToken: securityToken, }; } }); // listBuckets const buckets = await client.listBuckets(); console.log(buckets);
使用OIDCRoleARN
在Container ServiceKubernetes版中設定了Worker節點RAM角色後，對應節點內的Pod中的應用也可以像ECS上部署的應用一樣，通過中繼資料服務（Meta Data Server）擷取關聯角色的STS Token。但如果容器叢集上部署的是不可信的應用（比如部署客戶提交的應用，代碼也沒有開放），可能並不希望它們能通過中繼資料服務擷取Worker節點關聯執行個體RAM角色的STS Token。為了避免影響雲上資源的安全，同時又能讓這些不可信的應用安全地擷取所需的STS Token，實現應用層級的許可權最小化，可以使用RRSA（RAM Roles for Service Account）功能。該方式底層實現基於STS Token。阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，Credentials工具通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC介面換取綁定角色的STS Token。該方式無需提供AK或STS Token，消除了手動維護AK或STS Token的風險。詳情請參見通過RRSA配置ServiceAccount的RAM許可權實現Pod許可權隔離。
添加credentials依賴。
npm install @alicloud/credentials配置OIDC的RAM角色作為訪問憑證。
const OSS = require("ali-oss"); const Credential = require("@alicloud/credentials"); const credentialsConfig = new Credential.Config({ // 憑證類型。 type: "oidc_role_arn", // RAM角色名稱ARN，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定roleArn roleArn: '<RoleArn>', // OIDC供應商ARN，可以通過環境變數ALIBABA_CLOUD_OIDC_PROVIDER_ARN設定oidcProviderArn oidcProviderArn: '<OidcProviderArn>', // OIDC Token檔案路徑，可以通過環境變數ALIBABA_CLOUD_OIDC_TOKEN_FILE設定oidcTokenFilePath oidcTokenFilePath: '<OidcTokenFilePath>', // 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定roleSessionName roleSessionName: '<RoleSessionName>', // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"} // policy: "<Policy>", // 設定session到期時間 roleSessionExpiration: 3600 }); const credentialClient = new Credential.default(credentialsConfig); const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential(); const client = new OSS({ accessKeyId, accessKeySecret, stsToken: securityToken, refreshSTSTokenInterval: 0, // 由Credential控制accessKeyId、accessKeySecret和stsToken值的更新 refreshSTSToken: async () => { const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential(); return { accessKeyId, accessKeySecret, stsToken: securityToken, }; } }); const buckets = await client.listBuckets(); console.log(buckets);
使用CredentialsURI
適用於應用程式需要通過外部系統擷取阿里雲憑證，從而實現靈活的憑證管理和無密鑰訪問的情境。可以使用CredentialsURI初始化憑證提供者，底層實現基於STS Token。Credentials工具通過提供的URI擷取STS Token，完成憑證用戶端初始化。該方式無需提供AK或STS Token，消除了手動維護AK或STS Token的風險。
CredentialsURI指擷取STS Token的伺服器位址。
提供CredentialsURI響應的後端服務需要實現STS Token的自動重新整理邏輯，確保應用程式始終能擷取到有效憑證。
為了使Credentials工具正確解析和使用STS Token，URI必須遵循以下響應協議：
響應狀態代碼：200
響應體結構：
{ "Code": "Success", "AccessKeySecret": "AccessKeySecret", "AccessKeyId": "AccessKeyId", "Expiration": "2021-09-26T03:46:38Z", "SecurityToken": "SecurityToken" }
添加credentials依賴。
npm install @alicloud/credentials配置CredentialsURI作為訪問憑證。
const OSS = require("ali-oss"); const Credential = require("@alicloud/credentials"); // 通過憑證的 URI 初始化Credentials Client。 const credentialsConfig = new Credential.Config({ // 憑證類型。 type: "credentials_uri", // 擷取憑證的 URI，格式為http://local_or_remote_uri/，可以通過環境變數ALIBABA_CLOUD_CREDENTIALS_URI設定credentialsUri credentialsURI: '<CredentialsUri>' }); const credentialClient = new Credential.default(credentialsConfig); const credential = await credentialClient.getCredential(); // 初始化OSS const client = new OSS({ accessKeyId: credential.accessKeyId, accessKeySecret: credential.accessKeySecret, stsToken: credential.securityToken, refreshSTSTokenInterval: 0, // 由Credential控制accessKeyId、accessKeySecret和stsToken值的更新 refreshSTSToken: async () => { const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential(); return { accessKeyId, accessKeySecret, stsToken: securityToken, }; } }); // listBuckets const buckets = await client.listBuckets(); console.log(buckets);