當您需要通過命令列管理特定雲產品時，可安裝對應的 CLI 外掛程式。每個外掛程式對應一個雲產品，支援按需安裝、獨立更新，CLI 主程式保持輕量。所有外掛程式統一使用虛線（kebab-case）命名風格，並自動處理參數序列化，簡化調用體驗。
前提條件
已安裝阿里雲 CLI 3.3.0 或更高版本。安裝方法，請參見安裝/更新阿里雲 CLI。
確保阿里雲 CLI 已配置憑證。配置方法，請參見配置與管理身份憑證。
快速開始
以安裝 ecs 外掛程式為例，介紹安裝外掛程式並查詢地區列表的流程。
# 安裝外掛程式（以 ecs 外掛程式為例）
aliyun plugin install --name 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 Compute FC |
|
| 雲資料庫 RDS |
安裝、卸載和更新時，使用外掛程式全稱（例如 aliyun-cli-ecs）或產品 Code（例如 ecs），不區分大小寫。
安裝外掛程式
確認產品是否支援 CLI
可通過如下方式確認產品是否支援 CLI：
線上查詢（推薦）：訪問 CLI 中心，可按分類瀏覽、關鍵詞搜尋，查看產品列表、調用樣本。
命令列查詢：在 CLI 中列出所有可用外掛程式，或按關鍵詞搜尋：
查看遠程索引中所有可用的外掛程式：
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。
執行安裝
plugin install 支援兩種指定外掛程式的方式：使用 --name 標誌（如 aliyun plugin install --name ecs）或直接傳入名稱作為位置參數（如 aliyun plugin install ecs），效果相同。--name 標誌是 v3.3.14 新增的顯式寫法。
執行以下命令安裝外掛程式：
aliyun plugin install --name 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.針對不同安裝情境，可使用以下標誌：
標誌 | 樣本命令 | 說明 |
|
| 安裝單個外掛程式，僅接受一個名稱（v3.3.14+） |
|
| 大量安裝多個外掛程式，名稱以空格分隔，與 |
|
| 安裝指定版本，不指定則安裝最新穩定版 |
|
| 允許安裝預發布版本 |
|
| 從本地檔案（.zip/.tar.gz/.tgz）或 URL 安裝，適用於離線或特定區域網路環境 |
|
| 自訂外掛程式源地址（單次生效） |
以下為三種典型安裝方式的樣本：
# 方式 1：按名稱安裝單個外掛程式
aliyun plugin install --name ecs
# 方式 2：大量安裝多個外掛程式
aliyun plugin install --names ecs rds vpc
# 方式 3：從當地套件安裝（適用於離線或內網環境）
aliyun plugin install --package /path/to/ecs-plugin.zip
# 也支援從 URL 安裝
aliyun plugin install --package https://internal-mirror.example.com/plugins/ecs-plugin.tar.gzCLI 自動檢測作業系統和架構（例如 darwin-arm64、linux-amd64），下載匹配的外掛程式包。大量安裝時，單個外掛程式失敗不影響其餘外掛程式。部分外掛程式要求最低 CLI 版本，不滿足時會提示升級。
查看外掛程式詳情
安裝外掛程式後，可通過 aliyun plugin list 查看已安裝外掛程式的概要列表。如需查看某個外掛程式的詳細資料（如版本號碼、安裝路徑、支援的 API 版本列表等），執行以下命令：
# 查看指定外掛程式的詳細資料
aliyun plugin show --name ecs輸出包含：外掛程式名稱、目前的版本、安裝路徑、支援的 API 版本列表等。
使用外掛程式
產品外掛程式統一使用虛線（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 list 確認結果。
卸載外掛程式
執行以下命令卸載不再需要的外掛程式：
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!
......外掛程式全域設定
如果企業內網無法直接存取公網外掛程式源，或需要統一管理外掛程式下載地址，可通過 configure plugin-settings 子命令進行全域設定。設定儲存在 ~/.aliyun/plugin-settings.json 檔案中。
查看當前設定
執行以下命令查看當前外掛程式全域設定：
aliyun configure plugin-settings show設定自訂外掛程式源
執行以下命令設定自訂外掛程式源地址（適用於企業內網部署）：
aliyun configure plugin-settings set --source-base https://internal-mirror.example.com/cli-plugins設定完成後，執行以下命令確認設定已生效：
aliyun configure plugin-settings show清除自訂設定
執行以下命令清除自訂設定，恢複預設外掛程式源：
aliyun configure plugin-settings clear附錄
外掛程式命令列表
命令 | 說明 |
| 列出已安裝外掛程式 |
| 列出遠程可用外掛程式 |
| 查看指定外掛程式的詳細資料 |
| 搜尋命令對應的外掛程式 |
| 安裝外掛程式 |
| 更新外掛程式 |
| 卸載外掛程式 |
| 查看外掛程式全域設定 |
| 設定自訂外掛程式源地址 |
| 清除自訂外掛程式設定，恢複預設源 |
外掛程式環境變數列表
以下環境變數用於控制外掛程式行為：
環境變數 | 說明 |
| 自訂外掛程式目錄，預設為 |
| 設為 |
| 設為 |
| 設為 |
| 自訂外掛程式源地址（效果同 |
| 設定產品外掛程式預設 API 版本，例如： |
| 調節參數 help 資訊的單行輸出長度 |
常見問題
外掛程式安裝提示"no stable version available"
此提示表示該外掛程式僅提供預發布版本。要安裝預發布版本，在安裝命令中添加 --enable-pre 參數：
aliyun plugin install --name <外掛程式名> --enable-pre