阿里云 CLI 配置与能力指南
8月 13, 2026
说明：本文由 Codex 根据公开的阿里云官方文档与一次脱敏后的实际配置流程辅助生成，属于 AI 生成/整理内容，非作者原创。请读者自行甄别并交叉验证。
阿里云 CLI（Alibaba Cloud CLI）可以在终端中调用阿里云 OpenAPI，用统一的命令结构管理 ECS、RDS、OSS、容器服务等云产品。它适合日常查询、批量运维、Shell 脚本和 CI/CD，也支持多套身份配置、分页聚合、输出过滤、请求预演和插件化扩展。
本文以 macOS 本地开发环境为主，整理从安装、OAuth 登录到执行第一条命令的完整流程。示例中的 Profile、地域和资源标识均为通用占位信息，不包含真实账号 ID、Token、AccessKey 或私有资源数据。
安装与更新#
官方目前要求使用 3.3.0 或更高版本；低于 3.3.0 的版本已停止维护。macOS 推荐通过 Homebrew 安装：
brew install aliyun-cli确认命令路径和版本：
which aliyun
aliyun version如果最初通过 Homebrew 安装，后续也应通过 Homebrew 更新：
brew update
brew upgrade aliyun-cli
brew cleanup aliyun-cli非 Homebrew 安装且版本支持时，可以使用：
aliyun upgrade不要混用多种安装方式，否则 PATH 中可能同时存在多个 aliyun 可执行文件，造成“已经更新但版本没变”的错觉。
推荐的登录方式：OAuth#
本地开发环境优先使用 OAuth。它通过浏览器完成一次登录授权，CLI 获取并自动续期临时凭证，不需要长期保存和轮换 AccessKey。
前提条件：
- 阿里云 CLI 版本不低于 3.3.0。
- 本机可以打开浏览器。
- 使用阿里云主账号、已开启控制台登录的 RAM 用户，或企业 SSO 用户。
- RAM 用户或角色首次使用时，管理员需要在 RAM 的 OAuth 应用中安装官方 CLI 应用
official-cli，并分配对应身份。
创建名为 default 的 OAuth Profile：
aliyun configure --mode OAuth --profile default配置向导大致包含以下步骤：
- 选择站点。中国站输入
CN或直接回车；国际站选择INTL。 - CLI 自动打开浏览器；如果没有弹出，复制终端显示的登录 URL 手动打开。
- 登录阿里云并授权官方 CLI 应用。
- 返回终端，填写默认地域，例如
cn-hangzhou。 - 选择帮助信息语言，例如
zh。
OAuth 登录 URL、访问令牌、刷新令牌和本地配置文件都应视为敏感信息，不要发到聊天、截图或 Git 仓库中。
验证配置和当前身份#
查看本机已有 Profile：
aliyun configure list输出中的 * 表示当前默认 Profile，Valid 表示凭证当前有效。然后通过 STS 查询当前调用身份：
aliyun sts get-caller-identity首次执行某个云产品命令时，CLI 可能提示安装对应插件。可以按提示确认，或显式安装 STS 插件：
aliyun plugin install --name aliyun-cli-sts
aliyun sts get-caller-identity如果返回 AccountId、Arn 和 IdentityType 等字段，说明认证链路正常。公开分享终端输出时，应遮盖这些身份字段。
多账号和多环境管理#
CLI 可以保存多套 Profile，适合区分开发、测试和生产环境：
aliyun configure --mode OAuth --profile dev
aliyun configure --mode OAuth --profile prod切换默认 Profile：
aliyun configure switch --profile dev
aliyun configure list只让某一条命令使用指定 Profile：
aliyun ecs describe-instances \
--profile prod \
--region cn-shanghai也可以在当前 Shell 会话中指定：
export ALIBABA_CLOUD_PROFILE=devProfile 的选择优先级通常是：命令行 --profile、环境变量 ALIBABA_CLOUD_PROFILE、当前激活的 Profile。排查“为什么命令用了错误账号”时，应按这个顺序检查。
Linux 和 macOS 的配置文件默认位于：
~/.aliyun/config.json不要把这个文件提交到 Git，也不要直接复制给其他人。
CLI 的命令结构#
插件版 CLI 的通用格式是：
aliyun <云产品> <操作> [参数]例如查询 ECS 支持的地域：
aliyun ecs describe-regions --accept-language zh-CN查询某个地域中的 ECS 实例：
aliyun ecs describe-instances --region cn-hangzhou帮助信息是确认当前版本实际支持哪些命令和参数的可靠入口：
aliyun --help
aliyun ecs --help
aliyun ecs describe-instances --help
aliyun configure --help
aliyun plugin --help不同插件可能使用 kebab-case 参数名，并可能与旧版 OpenAPI 命令参数有所区别，因此不应只凭旧脚本猜测参数。
插件管理#
3.3.0 之后的 CLI 使用插件化架构，云产品能力可以按需安装和升级，不必一次性打包所有 OpenAPI 定义。
常用插件命令：
# 查看已安装插件
aliyun plugin list
# 搜索插件
aliyun plugin search ecs
# 安装插件
aliyun plugin install --name aliyun-cli-ecs
# 更新插件
aliyun plugin update --name aliyun-cli-ecs
# 查看插件详情
aliyun plugin show --name aliyun-cli-ecs如果希望在运行云产品命令时自动安装缺失插件，可以启用：
aliyun configure set --auto-plugin-install true自动安装方便交互使用；在 CI/CD 中则更适合显式固定安装步骤和版本，以提高构建可重复性。
常用能力项#
指定地域和接入点#
--region 会覆盖 Profile 中的默认地域：
aliyun ecs describe-instances --region cn-beijing大多数场景不需要手动指定 --endpoint。只有使用专有网络接入点、特殊网络环境或官方文档明确要求时再设置。
自动聚合分页结果#
对于支持分页的查询接口，可以使用 --pager 自动请求并合并多页结果：
aliyun ecs describe-instances \
--region cn-hangzhou \
--pager资源很多时要注意 API 限流、执行时间和输出体积。
使用 JMESPath 过滤输出#
--cli-query 可以只保留脚本真正需要的字段：
aliyun ecs describe-instances \
--region cn-hangzhou \
--cli-query 'Instances.Instance[].{Id:InstanceId,Name:InstanceName,Status:Status}'具体响应字段以当前插件帮助和 OpenAPI 返回结构为准。
表格化输出#
旧版兼容命令支持通过 --output 选择列并生成表格。例如：
aliyun ecs DescribeInstances \
--RegionId cn-hangzhou \
--output cols=InstanceId,InstanceName,Status rows=Instances.Instance插件版与旧版命令的操作名、参数名和输出选项可能不同，编写脚本前应先执行该层级的 --help。
请求预演#
插件式命令使用 --cli-dry-run 校验参数并打印请求，而不实际发送请求：
aliyun ecs describe-instances \
--biz-region-id cn-hangzhou \
--cli-dry-run对创建、停止、删除等写操作，建议先预演并人工检查资源 ID、地域、Profile 和参数。需要注意，--cli-dry-run 不能与 --pager 或 --quiet 同时使用。
调试日志#
调用失败时，可以临时提高日志级别：
aliyun ecs describe-instances \
--region cn-hangzhou \
--log-level DEBUG调试日志可能包含请求元数据或资源信息。排查完成后应恢复默认日志级别，公开粘贴前必须脱敏。
等待资源进入目标状态#
部分调用可以通过 --waiter 按 JMESPath 表达式轮询，直到返回值达到目标状态。这适合“创建后等待可用，再执行下一步”的脚本。具体表达式和目标字段取决于 API 响应，使用前应查阅当前命令帮助并设置合理的超时策略。
认证方式怎么选#
| 场景 | 推荐方式 | 原因 |
|---|---|---|
| 本地开发、日常运维 | OAuth | 浏览器登录、支持 MFA，不保存长期 AK |
| ECS 内运行的程序 | EcsRamRole | 从实例角色获取临时凭证 |
| 企业统一身份 | CloudSSO / OAuth | 便于集中管理、回收和审计 |
| CI/CD | OIDC、角色或临时凭证 | 避免长期密钥，权限可收敛 |
| 只能使用传统密钥的环境 | RAM 用户 AK | 应限制权限并定期轮换，不使用主账号 AK |
OAuth 依赖图形浏览器，不适合无桌面的远程服务器。服务器和流水线应优先使用实例角色、OIDC、STS 或其他临时凭证机制，而不是复制本地 OAuth 配置文件。
权限与安全建议#
- 日常操作使用 RAM 用户或 RAM 角色，避免长期以主账号身份调用 API。
- 按最小权限原则授权；查询任务不应获得创建或删除资源的权限。
- 不在命令历史、代码、CI 配置或日志中写入 AccessKey Secret、Token 和私钥。
- 不公开
AccountId、完整 ARN、实例 ID、域名、IP、Bucket 名称等资源信息。 - 写操作前同时检查 Profile、地域、资源 ID和预演结果。
- 不建议使用
--skip-secure-verify，它会跳过 HTTPS 证书校验。 - 配置文件和 OAuth 登录 URL都应视为敏感数据。
常见问题排查#
OAuth 浏览器没有自动打开#
复制终端打印的登录 URL，在浏览器中手动打开。还应检查本机回调端口和到阿里云登录站点的网络连通性。
提示没有 OAuth 调用权限#
如果 RAM 用户看到 The call is not authorized 或类似错误，通常需要管理员在 RAM 控制台安装 official-cli 应用，并把该用户或角色加入分配列表。
Profile 显示有效，但 API 返回无权限#
Valid 只说明凭证可以使用，不代表当前身份拥有目标 API 权限。运行 aliyun sts get-caller-identity 确认身份，再检查 RAM 权限策略、资源范围和条件限制。
命令提示缺少插件#
按提示安装，或显式执行：
aliyun plugin install --name <插件名>安装后通过 aliyun plugin list 确认状态，再重新运行原命令。
命令使用了错误的账号#
依次检查：
aliyun configure list
echo "$ALIBABA_CLOUD_PROFILE"同时确认原命令中是否带了 --profile，因为它的优先级最高。
一套最小可用流程#
对于一台新 macOS 开发机，可以把流程压缩成：
# 1. 安装
brew install aliyun-cli
# 2. 验证版本
aliyun version
# 3. OAuth 登录
aliyun configure --mode OAuth --profile default
# 4. 查看配置
aliyun configure list
# 5. 验证身份（首次执行可能提示安装 STS 插件）
aliyun sts get-caller-identity
# 6. 查看命令帮助并执行只读查询
aliyun ecs describe-regions --accept-language zh-CN完成这组步骤后，CLI 已具备调用云产品 OpenAPI 的基础条件。后续真正能执行哪些操作，取决于当前身份的 RAM 权限、资源所在地域以及对应云产品插件提供的命令。