阿里雲CLI 3.3.0起引入外掛程式化架構，將各雲產品的命令列調用能力拆分為獨立外掛程式。每個外掛程式對應一個雲產品，可按需安裝、獨立更新，CLI主程式保持輕量。所有外掛程式統一使用虛線（kebab-case）命名風格，並自動處理參數序列化，簡化調用體驗。
前提條件
已安裝阿里雲CLI 3.3.0或更高版本。安裝方法，請參見安裝CLI（Linux）。
確保阿里雲CLI已配置憑證。配置方法，請參見配置憑證。
快速開始
以安裝ecs外掛程式為例，介紹安裝外掛程式並查詢地區列表的流程。
# 安裝外掛程式（以ecs外掛程式為例）
aliyun plugin install --names ecs
# 調用API查詢地區列表
aliyun ecs describe-regions --accept-language zh-CN可通過aliyun ecs --help查看ecs外掛程式支援的所有命令。後續章節將介紹外掛程式命名規則、安裝管理、參數用法和進階特性。
外掛程式概述
外掛程式將各雲產品的API調用能力封裝為獨立的可執行程式，由CLI主程式統一調度。主要特性如下：
按需安裝：僅安裝所需雲產品外掛程式，減少CLI體積。
獨立更新：外掛程式獨立發布版本，無需升級CLI主程式。
統一命名：命令和參數使用虛線命名，例如
describe-instances、--accept-language。參數簡化：自動處理底層參數序列化，統一使用索引值對格式輸入。
完整協助：通過`--help`查看參數類型、描述和是否必填。
外掛程式安裝在~/.aliyun/plugins目錄下，清單記錄在manifest.json檔案中。
外掛程式命名規則
外掛程式命名格式為aliyun-cli-<產品Code>，產品Code與阿里雲OpenAPI一致，樣本如下：
外掛程式名稱 | 產品Code | 對應雲產品 |
|
| Elastic Compute Service |
|
| Function ComputeFC |
|
| 雲資料庫RDS |
安裝、卸載和更新時，使用外掛程式全稱（例如aliyun-cli-ecs）或產品Code（例如ecs），不區分大小寫。
安裝外掛程式
查看和搜尋外掛程式
查看遠程索引中所有可用的外掛程式：
aliyun plugin list-remote輸出樣本：
Total plugins available: 316
Name Latest Version Preview Status Local Version Description
---- -------------- ------- ------ ------------- -----------
aliyun-cli-ecs 0.1.0 No Installed 0.1.0 Aliyun CLI plugin for Elastic Compute Service operations.
aliyun-cli-fc 0.1.0 No Installed 0.1.0 Aliyun CLI plugin for Function Compute 3.0 operations.
aliyun-cli-acc 0.1.0 No Not installed - Aliyun CLI plugin for acs operations.要尋找特定命令所屬的外掛程式，可使用搜尋功能（支援首碼匹配）：
#搜尋包含ecs的外掛程式
aliyun plugin search ecs
#搜尋ecs產品下以describe開頭的命令
aliyun plugin search "ecs describe"CLI 外掛程式遵循語義化版本規範（SemVer）。0.x.x 為實驗性版本，不保證相容性；1.0.0 及以上為穩定版本，同一主要版本號內保持向後相容，主要版本號遞增可能存在非相容變更。
遠程索引預設緩衝1小時。如需強制重新整理，設定環境變數
ALIBABA_CLOUD_CLI_PLUGIN_NO_CACHE=true。
執行安裝
執行以下命令安裝外掛程式：
aliyun plugin install --names ecs安裝完成後，通過aliyun plugin list確認結果。
Name Version Description
---- ------- -----------
aliyun-cli-ecs 0.1.0 Aliyun CLI plugin for Elastic Compute Service operations.
aliyun-cli-fc 0.1.0 Aliyun CLI plugin for Function Compute 3.0 operations.根據需要，可使用以下選擇性參數：
情境 | 樣本命令 | 說明 |
同時安裝多個外掛程式 |
| 多個名稱以空格分隔 |
安裝指定版本 |
| 不指定則安裝最新穩定版 |
CLI自動檢測作業系統和架構（例如darwin-arm64、linux-amd64），下載匹配的外掛程式包。大量安裝時，單個外掛程式失敗不影響其餘外掛程式。部分外掛程式要求最低CLI版本，不滿足時會提示升級。
使用外掛程式
產品外掛程式統一使用虛線（kebab-case）命名。CLI自動將當前Profile中配置的憑證（AccessKey、STS Token等）、地區和逾時設定傳遞給產品外掛程式。--profile和--region等選項對外掛程式命令同樣生效，無需單獨配置。
命令格式：
aliyun <產品Code> <命令> [--參數名 值 ...]使用樣本
查看外掛程式協助資訊
使用aliyun <產品Code> --help或aliyun <產品Code> <命令> --help擷取協助資訊。例如查看ecs所有支援的命令：
aliyun ecs --help查看ecs外掛程式下特定命令的參數詳情：
aliyun ecs describe-regions --help輸出樣本：
......
--accept-language string, 根據漢語、英語和日語篩選返回結果。更多詳情，請參見[RFC
7231](https://tools.ietf.org/html/rfc7231)。取值範圍：
- zh-CN：簡體中文。
- zh-TW：繁體中文。
- en-US：英文。
- ja：日文。
- fr：法語。
- de：德語。
- ko：韓語。
預設值：zh-CN
--instance-charge-type string, 執行個體的計費方式，更多資訊，請參見https://help.aliyun.
com/document_detail/25398.html。取值範圍：
- PrePaid：訂用帳戶。此時，請確認自己的帳號支援餘額支付或者信用支付，
否則將報錯InvalidPayMethod。
- PostPaid：隨用隨付。
- SpotWithPriceLimit：設定上限價格。
- SpotAsPriceGo：系統自動出價，最高隨用隨付價格。
預設值：PostPaid
......協助資訊展示每個參數的類型、描述和是否必填。
查詢地區列表
執行以下命令查詢地區列表：
aliyun ecs describe-regions --accept-language zh-CN查詢輸出樣本：
{
"Regions": {
"Region": [
{
"LocalName": "華北1（青島）",
"RegionEndpoint": "ecs.cn-qingdao.aliyuncs.com",
"RegionId": "cn-qingdao"
},
{
"LocalName": "華北2（北京）",
"RegionEndpoint": "ecs.cn-beijing.aliyuncs.com",
"RegionId": "cn-beijing"
},
......進階用法
結構化參數輸入
外掛程式自動處理底層參數序列化。無論API使用何種參數風格（例如repeatList、flat、json），均使用相同的輸入方式：
數組參數：當參數（例如
attribute-name）為數組時，可重複使用特定參數。aliyun ecs describe-account-attributes\ --biz-region-id cn-hangzhou\ --attribute-name max-security-groups\ --attribute-name instance-network-type對象參數：當參數（例如
tag）為對象時，使用key=value格式。aliyun ecs describe-instances --biz-region-id cn-hangzhou\ --tag key=env value=prod
多版本API
部分雲產品存在多個API版本。通過aliyun plugin list查看已安裝外掛程式，描述中包含multi-version關鍵字的外掛程式支援多版本。例如：
Name Version Description
---- ------- -----------
aliyun-cli-ecs 0.1.0 Aliyun CLI plugin for Elastic Compute Service operations.
aliyun-cli-ess 0.1.0 Aliyun CLI plugin for Auto Scaling operations with multi-version API support.
aliyun-cli-fc 0.1.0 Aliyun CLI plugin for Function Compute 3.0 operations.對於支援多API版本的外掛程式，可使用--api-version參數指定API版本：
使用預設API版本
aliyun ess describe-scaling-groups --biz-region-id cn-hangzhou使用
--api-version指定API版本aliyun ess describe-scaling-groups --api-version 2022-02-22 --biz-region-id cn-hangzhou查看支援的API版本列表
aliyun ess list-api-versions
如果您經常使用某個特定版本，可通過環境變數設定預設值，避免每次指定--api-version。格式為ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION，其中<PRODUCT_CODE>為產品Code大寫形式。例如：
#添加環境變數並生效
echo 'export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22' >> ~/.bashrc
source ~/.bashrc設定後直接執行命令即使用該版本。命令中顯式指定--api-version時，優先順序高於環境變數。
更新和卸載外掛程式
更新外掛程式
更新指定外掛程式：
aliyun plugin update --name ecs更新所有已安裝的外掛程式：
aliyun plugin update如果外掛程式已是最新版本，CLI會提示無需更新。要更新到預發布版本，添加--enable-pre參數。
卸載外掛程式
aliyun plugin uninstall --name ecs操作完成後，通過aliyun plugin list確認結果。
配置自動安裝外掛程式
執行雲產品命令時，如果所需外掛程式未安裝，CLI可根據配置自動安裝。建議在非互動式環境（如 CI/CD、指令碼）或經常使用不同雲產品時啟用，以避免執行中斷或反覆手動安裝外掛程式。
啟用方式
通過命令啟用：
aliyun configure set --auto-plugin-install true或通過環境變數啟用（以Linux為例配置）：
#添加環境變數並生效
echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true' >> ~/.bashrc
source ~/.bashrc配置後執行aliyun configure get驗證。
如需允許自動安裝預發布版本：
aliyun configure set --auto-plugin-install-enable-pre true或通過環境變數配置（以Linux為例配置）。
#添加環境變數並生效
echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL_ENABLE_PRE=true' >> ~/.bashrc
source ~/.bashrc安裝策略
CLI根據運行環境選擇不同策略：
情境 | 行為 |
已啟用自動安裝 | 自動安裝外掛程式並繼續執行命令 |
互動式終端且未啟用自動安裝 | 提示確認是否安裝 |
非互動式環境（指令碼、管道） | 僅輸出安裝提示，不自動安裝 |
自動安裝輸出樣本：
#未安裝ecs外掛程式的情況下執行
aliyun ecs describe-regions --accept-language zh-CN
#自動安裝過程輸出
Plugin 'aliyun-cli-ecs' is required for command 'ecs describe-regions' but not installed.
Auto-installing plugin 'aliyun-cli-ecs' (including pre-release versions)...
Downloading aliyun-cli-ecs 0.1.0...
Plugin aliyun-cli-ecs 0.1.0 installed successfully!
......互動式環境未開啟自動安裝輸出樣本：
#未安裝ecs外掛程式的情況下執行
aliyun ecs describe-regions --accept-language zh-CN
#互動式安裝過程輸出
Plugin 'aliyun-cli-ecs' is required for command 'ecs describe-regions' but not installed.
Tip: Run 'aliyun configure set --auto-plugin-install true' to skip this prompt.
Do you want to install it? [Y/n]: y
Installing plugin 'aliyun-cli-ecs' (including pre-release versions)...
Downloading aliyun-cli-ecs 0.1.0...
Plugin aliyun-cli-ecs 0.1.0 installed successfully!
......附錄
外掛程式命令列表
命令 | 說明 |
| 列出已安裝外掛程式 |
| 列出遠程可用外掛程式 |
| 搜尋命令對應的外掛程式 |
| 安裝外掛程式 |
| 更新外掛程式 |
| 卸載外掛程式 |
外掛程式環境變數列表
以下環境變數用於控制外掛程式行為：
環境變數 | 說明 |
| 自訂外掛程式目錄，預設為 |
| 設為 |
| 設為 |
| 設為 |
| 設定產品外掛程式預設API版本，例如： |
| 調節參數help資訊的單行輸出長度。 |
常見問題
外掛程式安裝提示“no stable version available”
此提示表示該外掛程式僅提供預發布版本。要安裝預發布版本，在安裝命令中添加--enable-pre參數：
aliyun plugin install --names <外掛程式名> --enable-pre