阿里雲CLI從舊版遷移到外掛程式版需升級至3.3.0及以上版本，安裝獨立二進位外掛程式並調整命令風格為kebab-case，同時相容舊版命令但推薦逐步替換為外掛程式版以擷取新功能與安全更新。 - Alibaba Cloud CLI

本文介紹如何從 3.3.0 以下的舊版阿里雲 CLI 遷移到外掛程式版。

說明

本文面向 3.3.0 以下版本的使用者。如果 CLI 版本已是 3.3.0 或更高（通過 aliyun version查看），你使用的已是外掛程式版，無需遷移。

外掛程式版與舊版的區別

3.3.0 是引入外掛程式架構的版本。自該版本起，CLI 通過外掛程式機制執行雲產品操作命令。3.3.0 以下的版本稱為“舊版”。

舊版是 OpenAPI 透傳代理，命令名直接使用 API 名稱（如 DescribeInstances），參數與 API 參數一致（如 --RegionId）。外掛程式版中，每個雲產品的命令由獨立外掛程式提供。兩者執行相同的雲產品操作，但命令名、參數名和輸出格式存在差異。

說明

相容性說明：升級到 3.3.0+ 後，舊版命令文法仍然可用。你可以按自己的節奏逐步將指令碼切換到外掛程式版命令，無需一次性全量改寫。

對比案例

以DescribeRegionsAPI為例，外掛程式版命令：

aliyun ecs describe-regions --accept-language zh-CN

舊版命令：

aliyun ecs DescribeRegions --AcceptLanguage zh-CN

上例差異僅在命名風格。但在更複雜的命令中，外掛程式版可能重新設計了參數名，例如部分命令使用 --biz-region-id 而非 --region-id，與舊版的--RegionId 並非簡單的大小寫轉換。遷移時需通過<command> --help 或 OpenAPI門戶查看外掛程式版的正確參數名。

核心差異

改進點	舊版（< 3.3.0）	外掛程式版（≥ 3.3.0）
協助資訊	中繼資料產生，僅參數名列表	外掛程式內建，含取值範圍和用法樣本
產品更新	等 CLI 主程式整體發版，雲產品新特性更新速度較慢	外掛程式獨立更新，雲產品新特性更新速度快
外掛程式更新	升級整個 CLI 主程式	單外掛程式獨立更新，不影響其他產品
命令名	API Action（`DescribeInstances`）	統一 kebab-case 風格參數（`describe-instances`）
參數名	API 參數，風格可能不一致（`--RegionId`）	統一 kebab-case 風格參數（`--region-id`）

確認目前的版本

運行如下命令檢查版本號碼，輸出版本號碼 ≥ 3.3.0 即支援外掛程式版命令，低於 3.3.0 需先升級 CLI：

aliyun version

如需確認某個具體命令是否使用外掛程式版，運行 aliyun <command> <sub-command> --help：

外掛程式版：協助輸出包含全域參數段，參數名通常為 kebab-case 風格（如 --region-id）。
舊版：協助輸出僅有參數段，參數名通常為 PascalCase（如 --RegionId）。

尋找新版寫法

外掛程式版命令不是舊命令的簡單重新命名，無法通過大小寫轉換完成遷移。以下方式可尋找舊命令對應的外掛程式版寫法。

通過 OpenAPI 入口網站搜尋

已知舊版命令名（即 API 名稱）時，這是最直接的方式：

開啟 OpenAPI 門戶。
搜尋方塊中輸入舊版命令名（如 DescribeInstances），搜尋結果會列出匹配的 API。
點擊目標 API 進入詳情頁，填寫對應參數值，在右邊切換到CLI 樣本標籤頁。
CLI 風格（新版）下方顯示外掛程式版命令，API 原生風格（舊版）下方顯示舊版命令。複製新版命令替換指令碼中的舊命令。

說明

部分雲產品存在多個 API 版本。外掛程式版 CLI 通過 --api-version 參數指定調用的 API 版本。在門戶對照新舊命令時，注意選擇與當前使用版本一致的 API。

通過 CLI 首頁瀏覽

OpenAPI 門戶 CLI 首頁上，可按雲產品瀏覽所有已支援的外掛程式版命令及參數說明。

通過 `--help` 發現命令

安裝雲產品外掛程式後，通過 --help 逐級瀏覽可用命令和參數。例如查看 ECS 外掛程式的所有命令：

aliyun ecs --help

查看具體命令的用法和參數：

aliyun ecs describe-instances --help

通過 CLI Skills 查詢

訪問 CLI Skills 安裝 skill，通過 Agent 用自然語言描述需求，擷取對應的外掛程式版命令寫法。

執行遷移

步驟一：升級 CLI

確認目前的版本：

aliyun version

如果版本低於 3.3.0，參見安裝和更新阿里雲 CLI進行升級。升級無需卸載舊版，已有的憑證配置（~/.aliyun/config.json）不受影響。

升級後舊版命令仍可執行，現有指令碼不受影響。新產品支援、功能更新和安全修複僅在外掛程式版中提供。

步驟二：安裝外掛程式

安裝需要的雲產品外掛程式：

# 安裝單個外掛程式
aliyun plugin install --name ecs

# 大量安裝多個外掛程式
aliyun plugin install --names ecs oss vpc

也可通過環境變數開啟自動安裝。執行外掛程式版命令時如果對應外掛程式未安裝，CLI 自動下載並安裝：

export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

說明

export 僅對當前 shell 會話有效。要持久化，將上述命令添加到 shell 設定檔中：

Bash：~/.bashrc
Zsh：~/.zshrc

修改後執行 source ~/.bashrc（或 source ~/.zshrc）使配置生效。

步驟三：驗證命令

執行一條外掛程式版命令驗證是否工作正常：

aliyun ecs describe-regions

返回地區列表 JSON 即表示外掛程式版命令工作正常。

步驟四：更新指令碼

逐步將指令碼中的舊版命令替換為外掛程式版寫法：

識別指令碼中的舊版命令。特徵是第二個參數為 PascalCase（如 aliyun ecs DescribeInstances）。
通過 OpenAPI 入口網站搜尋舊命令名，找到對應的外掛程式版寫法。
用外掛程式版命令替換舊命令，參數名也需要一併替換。
測試替換後的指令碼。

舊版命令在新版中仍可執行，可按優先順序分批遷移。

說明

JSON 參數值內的欄位名不需要轉換。這些欄位名由 API 定義，與 CLI 參數命名風格無關。

特殊情境

CI/CD 流水線

非互動式環境下，CLI 不會彈出外掛程式安裝提示。處理方式：

流水線指令碼中預先安裝外掛程式：
```
aliyun plugin install --names ecs oss vpc
```

或設定環境變數開啟自動安裝：

export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

建議將環境變數寫入流水線的全域環境配置中（如 Jenkinsfile 的 environment 段、GitHub Actions 的 env 段），確保每次構建生效。

輸出解析指令碼

外掛程式版命令的 JSON 輸出欄位可能與舊版有差異。舊版直接返回 API 響應，外掛程式版可能對輸出做處理。如果指令碼中使用 jq、grep 等工具解析 CLI 輸出，替換命令後需對比驗證輸出格式。

複雜命令遷移

帶複雜參數的命令是遷移中最容易出錯的情境。

帶複雜 JSON 參數的命令

舊版：

aliyun slb AddBackendServers \
  --LoadBalancerId lb-xxx \
  --BackendServers '[{"ServerId":"i-aaa","Weight":100},{"ServerId":"i-bbb","Weight":80}]'

外掛程式版：

aliyun slb add-backend-servers \
  --load-balancer-id lb-xxx \
  --backend-servers '[{"ServerId":"i-aaa","Weight":100},{"ServerId":"i-bbb","Weight":80}]'

多行 heredoc 參數傳遞

JSON 參數較長時，使用 heredoc 提高可讀性：

aliyun ecs run-instances \
  --region cn-hangzhou \
  --instance-type ecs.g7.large \
  --image-id ubuntu_22_04_x64_20G_alibase_20230China.vhd \
  --security-group-id sg-xxx \
  --vswitch-id vsw-xxx \
  --system-disk "$(cat <<'EOF'
{"Size":40,"Category":"cloud_essd","PerformanceLevel":"PL1"}
EOF
)"

管道組合命令

舊版輸出 pipe jq處理的情境，擷取所有運行中執行個體的 ID 列表：

aliyun ecs DescribeInstances --RegionId cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

外掛程式版輸出結構可能不同，需根據實際返回調整 jq 路徑：

# 外掛程式版：先用 --help 確認輸出結構，再調整 jq 運算式
aliyun ecs describe-instances --region cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

說明

遷移管道命令時，先單獨執行外掛程式版命令查看完整輸出，確認 JSON 結構與預期一致後再調整 jq/grep 運算式。

舊版協助查看

安裝產品外掛程式後，aliyun <command> --help 優先展示外掛程式協助資訊。如需臨時查看舊版協助，設定環境變數：

export ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true

常見問題

升級後舊版 PascalCase 命令還能用嗎？

可以。CLI ≥ 3.3.0 向前相容。但建議儘快升級到最新版，以便於擷取最新的支援。

遷移後憑證需要重新設定嗎？

不需要。外掛程式版使用與舊版相同的憑證配置（~/.aliyun/config.json），升級後所有已配置的 profile 和環境變數憑證照常使用。

指令碼中能否新舊命令混用？

可以。同一指令碼中兩種風格共存，建議按優先順序漸進替換。

外掛程式安裝失敗怎麼辦？

按以下順序排查：

檢查網路是否可訪問 aliyuncli.alicdn.com。
確認外掛程式安裝目錄 ~/.aliyun/plugins/ 有寫入許可權。
確認 CLI 版本 ≥ 3.3.0（低版本不支援外掛程式功能）。執行 aliyun version 檢查。