# AWS CLI 版本 2 的迁移指南
本节包含将 AWS CLI 版本 1 更新为 AWS CLI 版本 2 的说明。AWS CLI 版本 2 建立在 AWS CLI 版本 1 的基础上，包括基于社区反馈的功能和增强功能。AWS CLI 版本 2 是 AWS CLI 的最新主版本，支持所有最新功能。版本 2 中引入的某些功能未向后移植到版本 1，您必须升级才能访问这些功能。
为防止出现意外问题，在迁移至版本 2 之前，请[了解这两个版本之间的区别](cliv2-migration-changes.md)。AWS CLI 版本 2 包括的新功能和更改可能要求您更新脚本或命令以实现向后兼容性。
AWS CLI 版本 1 和 2 使用相同的 `aws` 命令名称。如果您安装了两个版本，电脑将使用在搜索路径中找到的第一个版本。这可能会导致您的 `aws` 命令名调用旧 AWS CLI 版本，即使您安装了新版本也是如此。
要更新到 AWS CLI 版本 2，请按照以下说明之一进行操作：
+ 如果您之前安装了 AWS CLI 版本 1，请按照[从 AWS CLI 版本 1 安装 AWS CLI 版本 2](cliv2-migration-instructions.md)中的说明操作。
+ 如果您之前未安装 AWS CLI 版本 1，请按照[开始使用 AWS CLI](cli-chap-getting-started.md)中的说明操作。
## 使用 AWS CLI 迁移工具减少损坏
AWS CLI 版本 1 和 AWS CLI 版本 2 之间的行为有所不同，这可能需要您更新脚本或命令。在不验证现有脚本是否已安全迁移的情况下升级到 AWS CLI 版本 2，可能会在使用 AWS CLI 版本 2 运行脚本时遭遇意外影响，例如对 AWS 账户中的资源进行意外的更改。
您可以使用两种 AWS 拥有的工具来指导迁移。无论您使用哪种工具，我们都建议您参考 [AWS CLI 版本 2 中的新功能和变化](cliv2-migration-changes.md)指南中的 [AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)。
### 升级调试模式
升级调试模式是 AWS CLI 版本 1 中的一项功能，在版本 `1.44.0` 及更高版本中可用。启用此功能后，假设执行环境保持不变，则系统会检查您执行的每个 AWS CLI 命令，以确定它在 AWS CLI 版本 2 中是否可能有不同的行为。如果执行的命令在 AWS CLI 版本 2 中具有不同的行为，则命令输出旁边将显示一条警告，其中包含建议的操作，可以采取这些操作在 AWS CLI 版本 2 中保留 AWS CLI 版本 1 行为。
使用升级调试模式来指导迁移的主要原因是，此模式具有很高的覆盖范围，可以检测命令是否会面临行为变化。[AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)中描述的 15 个破坏性更改中有 14 个可以在升级调试模式下检测到。有关此功能的局限性，请参阅[使用升级调试模式将 AWS CLI 版本 1 升级到 AWS CLI 版本 2](cli-upgrade-debug-mode.md) 中的[限制](cli-upgrade-debug-mode.md#upgrade-mode-limitations)。另一方面，使用升级调试模式的主要缺点是其输出仅在其执行环境中相关；如果迁移到 AWS CLI 版本 2 后，环境中的任何 AWS CLI 配置设置发生变化，则仍可能发生破坏性更改，而您应该在更新后的环境中使用升级调试模式进行重新验证。
### AWS CLI v1 到 v2 迁移工具
AWS CLI v1 到 v2 迁移工具是一个独立的工具，可以与 Python 3.9 及更高版本一起使用。此工具是一个独立于 AWS CLI 运行的静态 linter。它会检查包含 AWS CLI 版本 1 命令的 bash 脚本，这些命令在 AWS CLI 版本 2 中可能具有不同的行为。对于它检测到在 AWS CLI 版本 2 中可能具有不同行为的大多数命令，它可以自动更新脚本中的命令，以便在 AWS CLI 版本 2 中保留 AWS CLI 版本 1 行为。
使用 AWS CLI v1 到 v2 迁移工具来指导迁移的主要原因是，它可以自动更新您的脚本，以便在 AWS CLI 版本 2 中保留 AWS CLI 版本 1 行为，从而节省您自行进行更新的时间和精力。另一方面，使用迁移工具的主要缺点是，它检测命令是否会面临行为变化的覆盖范围较小。作为一个静态工具，它不检查在运行时确定的行为变化。
## 在升级调试模式与 AWS CLI v1 到 v2 迁移工具之间进行选择
下表重点介绍了升级调试模式与 AWS CLI v1 到 v2 迁移工具之间的主要区别，可用于协助指导您为自己的使用案例选择正确的工具。
| 升级调试模式 | AWS CLI v1 到 v2 迁移工具 |
| --- | --- |
| 检测 AWS CLI 版本 1 和 AWS CLI 版本 2 之间的 15 个破坏性更改中的 14 个。 | 检测 AWS CLI 版本 1 和 AWS CLI 版本 2 之间的 15 个破坏性更改中的 7 个。 |
| 与任何可以运行 AWS CLI 的终端程序兼容。 | 仅支持检查 bash 脚本。 |
| 需要 AWS CLI 版本 1、版本 1.44.0 或更高版本。 | 独立于 AWS CLI 运行；它不要求安装 AWS CLI。 |
| 必须进行手动修复，才能在 AWS CLI 版本 2 中保留 AWS CLI 版本 1 行为。 | 自动修复它检测到的大多数 AWS CLI 版本 1 命令，这些命令在 AWS CLI 版本 2 中可能有不同的行为。 |
| 检测结果和建议的修复仅与执行它的执行环境（即 AWS CLI 配置）有关。 | 检测结果和建议的修复与环境无关。 |
| 需要执行每条被测的 AWS CLI 命令以了解行为变化。 | 不需要执行任何 AWS CLI 命令。对于每个 bash 脚本只需要执行一次。 |
| 正好有 5 个它将输出误报检测结果的已知情况。 | 正好有 3 个它将输出误报检测结果的已知情况。 |
下表显示了这两个迁移工具中的每一个工具支持哪些 [AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)。
| 破坏性更改 | 由升级调试模式检测到 | 由 AWS CLI v1 到 v2 迁移工具检测到 |
| --- | --- | --- |
| [添加了用于设置文本文件编码的环境变量](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | 是 | 否 |
| [原定设置情况下，二进制参数作为 base64 编码字符串进行传递](cliv2-migration-changes.md#cliv2-migration-binaryparam) | 是 | 是 |
| [改进了执行分段复制时 Amazon S3 处理文件属性和标签的方式](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | 是 | 是 |
| [不自动检索 `http://` 或 `https://` URL 以获取参数](cliv2-migration-changes.md#cliv2-migration-paramfile) | 是 | 否 |
| [原定设置情况下，使用分页程序处理所有输出](cliv2-migration-changes.md#cliv2-migration-output-pager) | 是 | 是 |
| [时间戳输出值标准化为 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) | 是 | 否 |
| [改进了 CloudFormation 部署的处理，而这不会导致任何更改](cliv2-migration-changes.md#cliv2-migration-cfn) | 是 | 是 |
| [更改了区域 Amazon S3 端点对于 `us-east-1` 区域的原定设置行为](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | 是 | 否 |
| [已更改区域 AWS STS 端点的原定设置行为](cliv2-migration-changes.md#cliv2-migration-sts-regional-endpoint) | 是 | 否 |
| [`ecr get-login` 已删除并替换为 `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | 是 | 是 |
| [AWS CLI 版本 2 对插件的支持会不断变化](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | 是 | 否 |
| [已删除隐藏别名支持](cliv2-migration-changes.md#cliv2-migration-aliases) | 是 | 是 |
| [不支持 `api_versions` 配置文件设置](cliv2-migration-changes.md#cliv2-migration-api-versions) | 是 | 否 |
| [AWS CLI 版本 2 仅使用签名 v4 对 Amazon S3 请求进行身份验证](cliv2-migration-changes.md#cliv2-migration-sigv4) | 是 | 否 |
| [AWS CLI 版本 2 与分页参数更一致](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 是 | 是 |
| [AWS CLI 版本 2 在所有命令间提供了更一致的返回代码](cliv2-migration-changes.md#cliv2-migration-return-codes) | 否 | 否 |
## 此部分中的其他主题
+ [AWS CLI 版本 2 中的新功能和变化](cliv2-migration-changes.md)
+ [从 AWS CLI 版本 1 安装 AWS CLI 版本 2](cliv2-migration-instructions.md)
+ [使用升级调试模式将 AWS CLI 版本 1 升级到 AWS CLI 版本 2](cli-upgrade-debug-mode.md)
+ [使用 AWS CLI v1 到 v2 迁移工具将 AWS CLI 版本 1 升级到 AWS CLI 版本 2](cli-migration-tool.md)
# AWS CLI 版本 2 中的新功能和变化
本主题介绍 AWS CLI 版本 1 和 AWS CLI 版本 2 之间的新功能和行为变化。这些变化可能要求您更新脚本或命令，以便在版本 2 中获得与版本 1 中相同的行为。
**Topics**
+ [AWS CLI 版本 2 新功能](#cliv2-migration-changes-features)
+ [AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改](#cliv2-migration-changes-breaking)
## AWS CLI 版本 2 新功能
AWS CLI 版本 2 是 AWS CLI 的最新主版本，支持所有最新功能。版本 2 中引入的某些功能无法向后兼容版本 1，您必须升级才能访问这些功能。这些功能如下所示：
**不需要 Python 解释器**
AWS CLI 版本 2 不需要单独安装 Python。它包括一个嵌入式版本。
**[向导](cli-usage-wizard.md)**
您可以将向导与 AWS CLI 版本 2 结合使用。此向导将引导您构建某些命令。
**[IAM Identity Center 身份验证IAM Identity Center 概念教程：AWS IAM Identity Center 和 Amazon S3AWS CLI 示例](cli-configure-sso.md)**
如果您的企业使用 AWS IAM Identity Center(IAM Identity Center)，则用户可以登录到 Active Directory、内置 IAM Identity Center 目录或[连接到 IAM Identity Center 的其他 IdP](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html)。然后，它们映射到允许您运行 AWS CLI 命令的 AWS Identity and Access Management (IAM) 角色。
**[自动提示](cli-usage-parameters-prompting.md)**
如果启用，当您运行 `aws` 命令时，AWS CLI 版本 2 可以提示您输入命令、参数和资源。
**[在 AWS CLI 中运行官方 Amazon ECR Public 映像或 Docker 映像](getting-started-docker.md)**
AWS CLI 的官方 Docker 映像提供 AWS 直接支持和维护的隔离、可移植性和安全性。这样，您可以在基于容器的环境中使用 AWS CLI 版本 2，而无需自行管理安装。
**[客户端分页程序](cli-usage-pagination.md#cli-usage-pagination-clientside)**
AWS CLI 版本 2 支持使用客户端分页程序处理输出。原定设置情况下，此功能处于启用状态，并通过操作系统的原定设置分页程序返回所有输出。
**[`aws configure import`](cli-configure-files.md#cli-config-aws_configure_import)**
导入从 AWS 管理控制台生成的 `.csv` 凭证。将导入一个配置文件名称与 IAM 用户名匹配的 `.csv` 文件。
**[https://docs.aws.amazon.com/cli/latest/reference/configure/list-profiles.html](https://docs.aws.amazon.com/cli/latest/reference/configure/list-profiles.html)**
列出您已经配置的所有配置文件的名称。
**[YAML 流输出格式](cli-usage-output-format.md#yaml-stream-output)**
`yaml` 和 `yaml-stream` 格式利用 [YAML](https://yaml.org) 格式，同时通过向您流式传输数据，使您在查看大型数据集时的响应能力更高。您可以在整个查询下载之前开始查看和使用 YAML 数据。
**[适用于 DynamoDB 的新的高级 `ddb` 命令](https://docs.aws.amazon.com/cli/latest/reference/ddb/index.html)**
AWS CLI 版本 2 具有高级 Amazon DynamoDB 命令 [https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/put.html](https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/put.html) 和 [https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/select.html](https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/select.html)。这些命令提供了一个简化的界面，用于将项目放入 DynamoDB 表中以及在 DynamoDB 表或索引中进行搜索。
**[https://docs.aws.amazon.com/cli/latest/reference/logs/tail.html](https://docs.aws.amazon.com/cli/latest/reference/logs/tail.html)**
AWS CLI 版本 2 具有自定义 `aws logs tail` 命令，用于跟踪 Amazon CloudWatch 日志组的日志。原定设置情况下，该命令从过去十分钟内所有关联的 CloudWatch Logs 流返回日志。
**[添加了对高级 `s3` 命令的元数据支持](cli-services-s3-commands.md#using-s3-commands-before-large)**
AWS CLI 版本 2 将 `--copy-props` 参数添加到高级 `s3` 命令中。使用此参数，您可以为 Amazon Simple Storage Service (Amazon S3) 配置其他元数据和标签。
**[`AWS_REGION`](cli-configure-envvars.md#envvars-list-AWS_REGION)**
AWS CLI 版本 2 有一个与 AWS SDK 兼容的环境变量，名为 `AWS_REGION`。此变量指定要向其发送请求的 AWS 区域。它覆盖 `AWS_DEFAULT_REGION` 环境变量，该变量仅适用于 AWS CLI。
## AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改
本节介绍 AWS CLI 版本 1 和 AWS CLI 版本 2 之间行为方面的所有变化。这些变化可能要求您更新脚本或命令，以便在版本 2 中获得与版本 1 中相同的行为。
**Topics**
+ [添加了用于设置文本文件编码的环境变量](#cliv2-migration-encodingenvvar)
+ [原定设置情况下，二进制参数作为 base64 编码字符串进行传递](#cliv2-migration-binaryparam)
+ [改进了执行分段复制时 Amazon S3 处理文件属性和标签的方式](#cliv2-migration-s3-copy-metadata)
+ [不自动检索 `http://` 或 `https://` URL 以获取参数](#cliv2-migration-paramfile)
+ [原定设置情况下，使用分页程序处理所有输出](#cliv2-migration-output-pager)
+ [时间戳输出值标准化为 ISO 8601 格式](#cliv2-migration-timestamp)
+ [改进了 CloudFormation 部署的处理，而这不会导致任何更改](#cliv2-migration-cfn)
+ [更改了区域 Amazon S3 端点对于 `us-east-1` 区域的原定设置行为](#cliv2-migration-s3-regional-endpoint)
+ [已更改区域 AWS STS 端点的原定设置行为](#cliv2-migration-sts-regional-endpoint)
+ [`ecr get-login` 已删除并替换为 `ecr get-login-password`](#cliv2-migration-ecr-get-login)
+ [AWS CLI 版本 2 对插件的支持会不断变化](#cliv2-migration-profile-plugins)
+ [已删除隐藏别名支持](#cliv2-migration-aliases)
+ [不支持 `api_versions` 配置文件设置](#cliv2-migration-api-versions)
+ [AWS CLI 版本 2 仅使用签名 v4 对 Amazon S3 请求进行身份验证](#cliv2-migration-sigv4)
+ [AWS CLI 版本 2 与分页参数更一致](#cliv2-migration-skeleton-paging)
+ [AWS CLI 版本 2 在所有命令间提供了更一致的返回代码](#cliv2-migration-return-codes)
### 添加了用于设置文本文件编码的环境变量
原定设置情况下，[Blob](cli-usage-parameters-types.md#parameter-type-blob)的文本文件使用与已安装的区域设置相同的编码。由于 AWS CLI 版本 2 使用的是 Python 的嵌入式版本，因此，不支持 `PYTHONUTF8` 和 `PYTHONIOENCODING` 环境变量。要将文本文件的编码设置为不同于区域设置，请使用 `AWS_CLI_FILE_ENCODING` 环境变量。下面的示例将 AWS CLI 设置为在 Windows 上使用 `UTF-8` 打开文本文件。
```
AWS_CLI_FILE_ENCODING=UTF-8
```
有关更多信息，请参阅 [为 AWS CLI 配置环境变量](cli-configure-envvars.md)。
### 原定设置情况下，二进制参数作为 base64 编码字符串进行传递
在 AWS CLI 中，有些命令需要使用 [base64](https://wikipedia.org/wiki/Base64) 编码的字符串，其他命令则需要使用 UTF-8 编码的字节字符串。在 AWS CLI 版本 1 中，在两种编码字符串类型之间传递数据通常需要一些中间处理。AWS CLI 版本 2 使处理二进制参数更加一致，从而有助于更可靠地将值从一个命令传递到另一个命令。
原定设置情况下，AWS CLI 版本 2 将所有二进制输入和二进制输出参数作为 base64 编码字符串 `blobs`（二进制大型对象）进行传递。有关更多信息，请参阅 [Blob](cli-usage-parameters-types.md#parameter-type-blob)。
要恢复为 AWS CLI 版本 1 行为，请使用 `cli\$1binary\$1format` 文件配置或 `--cli-binary-format` 参数。
### 改进了执行分段复制时 Amazon S3 处理文件属性和标签的方式
当您使用 `aws s3` 命名空间中的 AWS CLI 版本 1 命令将文件从一个 S3 存储桶位置复制到另一个存储桶位置，并且该操作使用[分段复制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CopyingObjctsMPUapi.html)时，源对象中的任何文件属性都不会复制到目标对象。
原定设置情况下，AWS CLI 版本 2 中的相应命令将所有标签和某些属性从源副本传输到目标副本。与 AWS CLI 版本 1 相比较，这可能会导致对 Amazon S3 端点进行更多 AWS API 调用。要更改 AWS CLI 版本 2 中 `s3` 命令的原定设置行为，请使用 `--copy-props` 参数。
有关更多信息，请参阅 [分段复制中的文件属性和标签](cli-services-s3-commands.md#using-s3-commands-before-tags)。
### 不自动检索 `http://` 或 `https://` URL 以获取参数
当参数值以 `http://` 或 `https://` 开头，但不使用返回的内容作为参数值时，AWS CLI 版本 2 不执行 `GET` 操作。因此，将从 AWS CLI 版本 2 中删除关联的命令行选项 `cli_follow_urlparam`。
如果您需要检索 URL 并将 URL 内容传递给参数值，我们建议您使用 `curl` 或类似的工具将 URL 的内容下载到本地文件。然后，使用 `file://` 语法读取该文件的内容，并将其用作参数值。
例如，以下命令不再尝试检索在 `http://www.example.com` 中找到的页面的内容，并将这些内容作为参数传递。相反，它将文字文本字符串 `https://example.com` 作为参数传递。
```
$ aws ssm put-parameter \
--value http://www.example.com \
--name prod.microservice1.db.secret \
--type String 2
```
如果您需要检索 Web URL 的内容并将其用作参数，则可以在版本 2 中执行以下操作。
```
$ curl https://my.example.com/mypolicyfile.json -o mypolicyfile.json
$ aws iam put-role-policy \
--policy-document file://./mypolicyfile.json \
--role-name MyRole \
--policy-name MyReadOnlyPolicy
```
在前面的示例中，`-o` 参数指示 `curl` 将文件保存在与源文件同名的当前文件夹中。第二个命令检索该下载文件的内容，并将内容作为 `--policy-document` 的值传递。
### 原定设置情况下，使用分页程序处理所有输出
原定设置情况下，AWS CLI 版本 2 会通过操作系统的原定设置分页程序返回所有输出。此程序是 Linux 或 macOS 上的 [https://ss64.com/bash/less.html](https://ss64.com/bash/less.html) 程序，以及 Windows 上的 [https://docs.microsoft.com/windows-server/administration/windows-commands/more](https://docs.microsoft.com/windows-server/administration/windows-commands/more) 程序。这样，通过一次一页显示服务的输出，从而帮助您浏览大量输出。
您可以将 AWS CLI 版本 2 配置为使用其他分页程序或根本不使用分页程序。有关更多信息，请参阅 [客户端分页程序](cli-usage-pagination.md#cli-usage-pagination-clientside)。
### 时间戳输出值标准化为 ISO 8601 格式
原定设置情况下，AWS CLI 版本 2 以 [ISO 8601 格式](https://wikipedia.org/wiki/ISO_8601)返回所有时间戳响应值。在 AWS CLI 版本 1 中，命令以 HTTP API 响应返回的任何格式返回时间戳值，而格式可能因服务而异。
要查看以由 HTTP API 响应返回的格式表示的时间戳，请在 `config` 文件中使用 `wire` 值。有关更多信息，请参阅 `cli\$1timestamp\$1format`。
### 改进了 CloudFormation 部署的处理，而这不会导致任何更改
原定设置情况下，在 AWS CLI 版本 1 中，如果您部署的 CloudFormation 模板未导致任何更改，则 AWS CLI 返回失败错误代码。如果您不认为这是一个错误，并希望您的脚本继续运行，这可能导致出现问题。在 AWS CLI 版本 1 中，可以通过添加返回 `0` 的标志 `-–no-fail-on-empty-changeset` 来解决此问题。
因为这是常见使用案例，所以，当部署没有导致更改并且操作返回空更改集时，AWS CLI 版本 2 原定设置为返回成功的退出代码 `0`。
要恢复到原始行为，请添加标志 `--fail-on-empty-changeset`。
### 更改了区域 Amazon S3 端点对于 `us-east-1` 区域的原定设置行为
当您将 AWS CLI 版本 1 配置为使用 `us-east-1` 区域时，AWS CLI 使用物理托管在 `us-east-1` 区域中的全局 `s3.amazonaws.com` 端点。AWS CLI 版本 2 会在指定区域时使用真正的区域端点 `s3.us-east-1.amazonaws.com`。要强制 AWS CLI 版本 2 使用全局端点，您可以将命令的区域设置为 `aws-global`。
### 已更改区域 AWS STS 端点的原定设置行为
原定设置情况下，AWS CLI 版本 2 会将所有 AWS Security Token Service (AWS STS) API 请求发送到当前配置的 AWS 区域的区域端点。
默认情况下，AWS CLI 版本 1 的 `1.42.0` 之前的任何发行版都会将 AWS STS 请求发送到全球 AWS STS 端点。您可以使用 [https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-config-sts_regional_endpoints](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-config-sts_regional_endpoints) 设置来控制版本 1 中的此原定设置行为。
不低于 `1.42.0` 的任何版本都使用区域端点作为默认值，如果您要从这些较新的版本迁移到 AWS CLI 版本 2，则此行为将保持不变。
### `ecr get-login` 已删除并替换为 `ecr get-login-password`
AWS CLI 版本 2 将 `aws ecr get-login` 命令替换为 `aws ecr get-login-password` 命令，以改进与容器身份验证的自动集成。
`aws ecr get-login-password` 命令可降低在进程列表、shell 历史记录或其他日志文件中公开您的凭证的风险。它还提高了与 `docker login` 命令的兼容性，从而改善自动化处理的效果。
该 `aws ecr get-login-password` 命令在 AWS CLI 版本 1.17.10 及更高版本以及 AWS CLI 版本 2 中提供。为保持向后兼容性，较早的 `aws ecr get-login` 命令仍在 AWS CLI 版本 1 中可用。
使用 `aws ecr get-login-password` 命令，您可以替换以下用于检索密码的代码。
```
$ (aws ecr get-login --no-include-email)
```
要降低在 shell 历史记录或日志中公开密码的风险，请改用以下示例命令。在此示例中，密码会被直接传送给 `docker login` 命令，通过 `--password-stdin` 选项分配给密码参数。
```
$ aws ecr get-login-password | docker login --username AWS --password-stdin MY-REGISTRY-URL
```
有关更多信息，请参阅《AWS CLI 版本 2 参考指南》**中的 [https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login-password.html](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login-password.html)。
### AWS CLI 版本 2 对插件的支持会不断变化
AWS CLI 版本 2 中的插件支持完全是暂时的，目的是在发布更新的稳定版插件接口之前帮助用户从 AWS CLI 版本 1 进行迁移。不保证某个特定的插件甚或是 AWS CLI 插件接口在未来版本的 AWS CLI 版本 2 中受支持。如果您依赖于插件，请务必锁定到 AWS CLI 的特定版本，并在升级时测试插件的功能。
要启用插件支持，请在 `~/.aws/config` 中创建 `[plugins]` 区段。
```
[plugins]
cli_legacy_plugin_path = /python3.7/site-packages
=
```
在 `[plugins]` 区段中，定义 `cli_legacy_plugin_path` 变量并将其值设置为插件模块所在的 Python 站点包路径。然后，您可以通过提供插件名称 (`plugin-name`) 以及包含插件源代码的 Python 模块 (`plugin-module`) 的文件名，对插件进行配置。AWS CLI 会通过导入插件的 `plugin-module` 并调用插件的 `awscli_initialize` 函数来加载每个插件。
### 已删除隐藏别名支持
AWS CLI 版本 2 不再支持版本 1 中支持的以下隐藏别名。
在下表中，第一列显示适用于所有版本（包括 AWS CLI 版本 2）的服务、命令和参数。第二列显示不再适用于 AWS CLI 版本 2 的别名。
| 有效的服务、命令和参数 | 过时的别名 |
| --- | --- |
| cognito-identity create-identity-pool open-id-connect-provider-arns | open-id-connect-provider-ar-ns |
| storagegateway describe-tapes tape-arns | tape-ar-ns |
| storagegateway.describe-tape-archives.tape-arns | tape-ar-ns |
| storagegateway.describe-vtl-devices.vtl-device-arns | vtl-device-ar-ns |
| storagegateway.describe-cached-iscsi-volumes.volume-arns | volume-ar-ns |
| storagegateway.describe-stored-iscsi-volumes.volume-arns | volume-ar-ns |
| route53domains.view-billing.start-time | start |
| deploy.create-deployment-group.ec2-tag-set | ec-2-tag-set |
| deploy.list-application-revisions.s3-bucket | s-3-bucket |
| deploy.list-application-revisions.s3-key-prefix | s-3-key-prefix |
| deploy.update-deployment-group.ec2-tag-set | ec-2-tag-set |
| iam.enable-mfa-device.authentication-code1 | authentication-code-1 |
| iam.enable-mfa-device.authentication-code2 | authentication-code-2 |
| iam.resync-mfa-device.authentication-code1 | authentication-code-1 |
| iam.resync-mfa-device.authentication-code2 | authentication-code-2 |
| importexport.get-shipping-label.street1 | street-1 |
| importexport.get-shipping-label.street2 | street-2 |
| importexport.get-shipping-label.street3 | street-3 |
| lambda.publish-version.code-sha256 | code-sha-256 |
| lightsail.import-key-pair.public-key-base64 | public-key-base-64 |
| opsworks.register-volume.ec2-volume-id | ec-2-volume-id |
### 不支持 `api_versions` 配置文件设置
AWS CLI 版本 2 不支持通过使用 `api_versions` 配置文件设置调用较早版本的 AWS 服务 API。所有 AWS CLI 命令现在可调用端点当前支持的服务 API 的最新版本。
### AWS CLI 版本 2 仅使用签名 v4 对 Amazon S3 请求进行身份验证
AWS CLI 版本 2 不支持使用较早的签名算法对发送到 Amazon S3 端点的服务请求进行加密身份验证。这种签名会在每个 Amazon S3 请求中自动发生，但仅支持[签名版本 4 签名流程](https://docs.aws.amazon.com/AmazonS3/latest/userguide/reference_aws-signing.html)。您无法配置签名版本。现在，所有 Amazon S3 存储桶预签名 URL 都只使用 Sigv4，最长有效期为一周。
### AWS CLI 版本 2 与分页参数更一致
在 AWS CLI 版本 1 中，如果您在命令行上指定分页参数，则会按预期关闭自动分页。但是，当您使用带有 `‐‐cli-input-json` 参数的文件指定分页参数时，并不会关闭自动分页，这可能会导致意外输出。无论您如何提供参数，AWS CLI 版本 2 都会关闭自动分页。
### AWS CLI 版本 2 在所有命令间提供了更一致的返回代码
与 AWS CLI 版本 1 相比，AWS CLI 版本 2 在所有命令间更加一致，并正确返回适当的退出代码。我们还添加了退出代码 252、253 和 254。有关退出代码的更多信息，请参阅[AWS CLI 中的命令行返回代码](cli-usage-returncodes.md)。
如果您依赖于 AWS CLI 版本 1 使用返回代码值的方式，建议检查退出代码以确保您获得了预期的值。
# 从 AWS CLI 版本 1 安装 AWS CLI 版本 2
本主题提供用于从 AWS CLI 版本 1 迁移至 AWS CLI 版本 2 的说明。
AWS CLI 版本 1 和 2 使用相同的 `aws` 命令名称。如果您安装了两个版本，电脑将使用在搜索路径中找到的第一个版本。如果您之前安装过 AWS CLI 版本 1，建议您执行以下操作之一来使用 AWS CLI 版本 2：
+ **推荐** – [卸载 AWS CLI 版本 1 并仅使用 AWS CLI 版本 2](#cliv2-migration-instructions-migrate)。
+ [要同时安装这两个版本](#cliv2-migration-instructions-side-by-side)，请使用操作系统的功能为两个 `aws` 命令之一创建具有不同名称的符号链接 (symlink) 或别名。
有关版本 1 和版本 2 之间的突破性更改的信息，请参阅 [AWS CLI 版本 2 中的新功能和变化](cliv2-migration-changes.md)。
## 将版本 1 替换为版本 2
执行以下步骤以将 AWS CLI 版本 1 替换为 AWS CLI 版本 2。
**将 AWS CLI 版本 1 替换为 AWS CLI 版本 2**
1. 通过在 [AWS CLI 版本 2 中的新功能和变化](cliv2-migration-changes.md)中确认版本 1 和版本 2 之间的任何突破性更改，为迁移准备任何现有的脚本。您可以按照[使用升级调试模式将 AWS CLI 版本 1 升级到 AWS CLI 版本 2](cli-upgrade-debug-mode.md)中的说明，使用升级调试模式功能来指导您的准备工作。
1. 按照[安装、更新和卸载 AWS CLI 版本 1](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html) 中适用于您的操作系统的卸载说明操作，卸载 AWS CLI 版本 1。
1. 使用以下命令确认 AWS CLI 已完全卸载。
```
$ aws --version
```
根据输出完成下列操作之一：
+ **没有返回任何版本：**您已成功卸载 AWS CLI 版本 1，可以继续执行下一步。
+ **返回了版本：**您仍有 AWS CLI 版本 1 的安装。有关问题排查步骤，请参阅[卸载 AWS CLI 后，“`aws --version`”命令返回一个版本](cli-chap-troubleshooting.md#tshoot-uninstall-1)。执行故障排除步骤，直到不会收到版本输出。
1. 按照[安装或更新最新版本的 AWS CLI](getting-started-install.md)中适用于您的操作系统的安装说明安装 AWS CLI 版本 2。
## 并排安装
要同时安装这两个版本，请使用操作系统的功能为两个 `aws` 命令之一创建具有不同名称的符号链接 (symlink) 或别名。
1. 按照[安装或更新最新版本的 AWS CLI](getting-started-install.md)中适用于您的操作系统的安装说明安装 AWS CLI 版本 2。
1. 使用操作系统的功能为两个 `aws` 命令中的一个命令创建具有不同名称的符号链接或别名，例如，将 *`aws2`* 用于 AWS CLI 版本 2。以下是用于 AWS CLI 版本 2 的符号链接示例。将 *PATH* 替换为您的安装位置。
------
#### [ Linux and macOS ]
您可以在 Linux 和 macOS 上使用[符号链接](https://www.linux.com/topic/desktop/understanding-linux-links/)或[别名](https://www.linux.com/topic/desktop/aliases-diy-shell-commands/)。
```
$ alias aws2='PATH'
```
------
#### [ Windows command prompt ]
[https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/doskey](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/doskey)Windows 上的
```
C:\> doskey aws2=PATH
```
------
# 使用升级调试模式将 AWS CLI 版本 1 升级到 AWS CLI 版本 2
本主题介绍 AWS CLI 版本 1 中的升级调试模式。
我们建议 AWS CLI 版本 1 的用户升级到 AWS CLI 版本 2，以便使用新功能以及增强性能。AWS CLI 版本 1 和 AWS CLI 版本 2 之间的行为有所不同，可能需要您更新脚本或命令来获得相同的行为。当您使用在 AWS CLI 版本 2 中行为不同的功能时，AWS CLI 版本 1 中的升级调试模式会输出警告。此功能通过自动检测在升级到 AWS CLI 版本 2 之前需要修改的 AWS CLI 版本 1 命令，来改善升级体验，以防止出现意外问题。
有关更多详细信息，请参阅 [AWS CLI 版本 2 中的新功能和变化](cliv2-migration-changes.md)中的 [AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)。
## 先决条件
版本 `1.44.0` 的 AWS CLI 中引入了升级调试模式功能。
使用 AWS CLI 版本 1 运行 `aws --version`，并验证 AWS CLI 版本是否为 `1.44.0` 或更高版本。
如果版本低于 `1.44.0`，请参阅[安装、更新和卸载 AWS CLI](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html)。
## 工作原理
如果启用升级调试模式，该模式会检测在 AWS CLI 版本 2 中有突破性更改的更新功能的使用情况。如果您在升级到 AWS CLI 版本 2 后使用我们的 [AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)中列出的命令或功能，则输出中将会显示一条警告。突破性更改检测基于所使用的命令、提供的参数、执行环境（例如环境变量、配置设置等），并且在某些情况下，还基于所使用的 AWS 账户中资源的内容或配置。
这些警告描述了为防止升级到 AWS CLI 版本 2 时出现意外问题而采取的措施。进行警告消息所建议的更改后，您可以通过重新运行命令以验证警告不再显示，来确认命令已成功更新。警告已得到解决表明，该命令不太可能再经历升级到 AWS CLI 版本 2 时所述的重大更改。
下面的示例演示了这些警告的具体形式。此命令演示一个警告示例。所有警告文本都以“AWS CLI V2 升级警告”开头，后面跟随具体的警告消息。在这种情况下，会输出一个警告，因为该命令依赖 AWS CLI 来获取 URL 的内容并将内容用作 `--template-body` 参数值，而该功能在 AWS CLI 版本 2 中已经移除。
```
$ aws cloudformation create-stack \
--stack-name "stack012345" \
--template-body "https://s3.amazonaws.com/amzn-s3-demo-bucket/template.json"
AWS CLI v2 UPGRADE WARNING: For input parameters that have a prefix of http:// or
https://, AWS CLI v2 will not automatically request the content of the URL for
the parameter, and the `cli_follow_urlparam` option has been removed. See
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-paramfile.
```
下表列出了所有突破性更改，以及如何避免在 AWS CLI 版本 2 中遇到突破性更改。在调试模式下解决警告的修复操作以粗体形式显示。
| 突破性更改 | 在 v1 上，迁移到 v2 行为 | 在 v2 上，保留 v1 行为 |
| --- | --- | --- |
| [添加了用于设置文本文件编码的环境变量](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | 取消设置 PYTHONUTF8 和 PYTHONIOENCODING 环境变量。 | 将 AWS\$1CLI\$1FILE\$1ENCODING 环境变量设置为 v1 中指定的编码。 |
| [原定设置情况下，二进制参数作为 base64 编码字符串进行传递](cliv2-migration-changes.md#cliv2-migration-binaryparam) | 使用 base64 对参数的值进行编码。如果该参数是从文件加载的，则使用 base64 对文件内容进行编码。 | 将 cli\$1binary\$1format 设置为 raw-in-base64-out。 |
| [改进了执行分段复制时 Amazon S3 处理文件属性和标签的方式](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | 不适用。无法在版本 1 中迁移到版本 2 行为。 | 使用 --copy-props none 参数。 |
| [不自动检索 `http://` 或 `https://` URL 以获取参数](cliv2-migration-changes.md#cliv2-migration-paramfile) | 使用 curl（或替代工具）将 URL 的内容下载到本地文件。然后，使用 [file://](https://docs.aws.amazon.com/cli/v1/userguide/cli-usage-parameters-file.html) 将文件内容加载到该参数中。或者，将 cli\$1follow\$1urlparam 配置为 false 以将原始 URL 指定为参数值。 | 不适用。无法在版本 2 中保留版本 1 行为。 |
| [原定设置情况下，使用分页程序处理所有输出](cliv2-migration-changes.md#cliv2-migration-output-pager) | 不适用。无法在版本 1 中迁移到版本 2 行为。 | 将 cli\$1pager 设置或 AWS\$1PAGER 变量设定为空字符串。 |
| [时间戳输出值标准化为 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) | 将 cli\$1timestamp\$1format 设置为 iso8601。 | 将 cli\$1timestamp\$1format 设置为 wire。 |
| [改进了 CloudFormation 部署的处理，而这不会导致任何更改](cliv2-migration-changes.md#cliv2-migration-cfn) | 使用 --no-fail-on-empty-changeset 参数。 | 使用 --fail-on-empty-changeset 参数。 |
| [更改了区域 Amazon S3 端点对于 `us-east-1` 区域的原定设置行为](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | 将 AWS\$1ENDPOINT\$1URL\$1S3 环境变量或 --endpoint-url 命令行选项设置为 us-east-1 [区域 URL](https://docs.aws.amazon.com/general/latest/gr/s3.html#s3_region)。 | 使用 --region aws-global 命令行选项。 |
| [`ecr get-login` 已删除并替换为 `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | （1.17.10 或更高版本）使用 [`ecr get-login` 已删除并替换为 `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) 并将输出通过管道传输到 docker 命令。 | 不适用。无法在版本 2 中保留版本 1 行为。 |
| [AWS CLI 版本 2 对插件的支持会不断变化](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | 不适用。无法在版本 1 中迁移到版本 2 行为。 | 将 [cli\$1legacy\$1plugin\$1path](https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#plugins) 配置到配置文件的 [plugins] 部分中。在版本 2 中测试插件，锁定版本 2 的版本，并在每次升级时测试您的插件。 |
| [已删除隐藏别名支持](cliv2-migration-changes.md#cliv2-migration-aliases) | 从使用过时的隐藏别名切换为[已删除隐藏别名支持](cliv2-migration-changes.md#cliv2-migration-aliases)，这种方式在所有版本中都能正常工作。 | 不适用。无法在版本 2 中保留版本 1 行为。 |
| [不支持 `api_versions` 配置文件设置](cliv2-migration-changes.md#cliv2-migration-api-versions) | 将您使用的旧版本 API 迁移到最新的 API 版本并进行测试，然后从您的配置设置中移除 [api\$1versions](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-config-api_versions)。 | 不适用。无法在版本 2 中保留版本 1 行为。 |
| [AWS CLI 版本 2 仅使用签名 v4 对 Amazon S3 请求进行身份验证](cliv2-migration-changes.md#cliv2-migration-sigv4) | 将签名版本指定为版本 4（参见[在请求身份验证中指定签名版本](https://docs.aws.amazon.com/AmazonS3/latest/API/specify-signature-version.html)）。 | 不适用。无法在版本 2 中保留版本 1 行为。 |
| [AWS CLI 版本 2 与分页参数更一致](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 将输入 JSON 参数中的分页参数移到命令本身。 | 从输入 JSON 参数中移除分页参数。 |
| [AWS CLI 版本 2 在所有命令间提供了更一致的返回代码](cliv2-migration-changes.md#cliv2-migration-return-codes) | 不适用。无法在版本 1 中迁移到版本 2 行为。 | 不适用。无法在版本 2 中保留版本 1 行为。 |
## 限制
我们强烈建议客户查看我们的 [AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)。
### 不支持的突破性更改检测
升级调试模式功能支持除 [AWS CLI 版本 2 在所有命令间提供了更一致的返回代码](cliv2-migration-changes.md#cliv2-migration-return-codes)之外的所有突破性更改。此模式无法处理您使用 AWS CLI 下游所返回错误代码的方式。
### 有条件的突破性更改检测
[时间戳输出值标准化为 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp)的检测是检测依赖于 AWS 账户状态的唯一情况，如果账户资源以后发生更新，可能会出现突破性更改。如果服务的 API 响应中不包含时间戳，则不会针对此突破性更改进行任何检测。
如果您依赖于 AWS CLI 命令返回的时间戳格式，并且尚未将 AWS CLI 配置为使用 ISO 8601，请格外小心，以确保在升级到版本 2 后时间戳处理过程不会出错。
### 无法解决的突破性更改检测
升级调试模式输出的一些警告无法通过修改命令或环境来解决。在以下情况下，只要您使用相应的功能，升级调试模式就会始终输出警告：
+ [AWS CLI 版本 2 对插件的支持会不断变化](cliv2-migration-changes.md#cliv2-migration-profile-plugins)：如果您依赖于[配置文件](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html)中的插件，升级调试模式将始终输出无法解决的警告。此模式无法保证您的任何插件在 AWS CLI 版本 2 中正常运行。
+ [改进了执行分段复制时 Amazon S3 处理文件属性和标签的方式](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata)：如果 `aws s3` 用于执行存储桶到存储桶的 Amazon S3 复制，升级调试模式将始终输出无法解决的警告。
### 误检测
升级调试模式输出的警告并不能保证升级到 AWS CLI v2 后会遇到突破性更改。在以下情况下，即使在 AWS CLI v2 中没有引入突破性更改，升级调试模式仍会输出警告：
+ [添加了用于设置文本文件编码的环境变量](cliv2-migration-changes.md#cliv2-migration-encodingenvvar)：如果指定了 `PYTHONUTF8` 或 `PYTHONIOENCODING` 环境变量来设置文本文件编码，并且所指定的编码已经与已安装的区域设置匹配，则警告可能是误检测，因为调试模式不会检查编码是否与已安装的区域设置匹配。
+ [改进了执行分段复制时 Amazon S3 处理文件属性和标签的方式](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata)：如果使用 `aws s3` 执行存储桶到存储桶的 Amazon S3 复制，并且由于源对象小于[分段阈值大小](https://docs.aws.amazon.com/cli/latest/topic/s3-config.html#multipart-threshold)而未采用分段复制方式，则会输出误检测。
+ [时间戳输出值标准化为 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp)：如果 cli\$1timestamp\$1format 配置设置设定为 wire（默认值），并且服务返回的时间戳是 ISO 8601 格式，则会输出误检测。
+ [改进了 CloudFormation 部署的处理，而这不会导致任何更改](cliv2-migration-changes.md#cliv2-migration-cfn)：如果将 `--fail-on-empty-changeset` 标志与 `aws cloudformation deploy` 命令一起使用，并且生成的更改集为空，则会输出误检测。此外，如果更改集非空并且未使用 `--no-fail-on-empty-changeset`，则会输出误检测。
+ [更改了区域 Amazon S3 端点对于 `us-east-1` 区域的原定设置行为](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint)：如果使用 `aws s3` 或 `aws s3api` 执行 Amazon S3 操作，并且该区域配置为 `us-east-1`，但配置 `s3.us_east_1_regional_endpoint` 未配置为区域性，并且由于[端点配置设置](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-endpoints.html#endpoints-precedence)而使用全球 Amazon S3 端点来处理请求，则警告可能是误检测，因为调试模式不检查已配置的端点设置。
## 配置升级调试模式
您可以使用以下按优先顺序列出的方法启用或禁用升级调试模式：
+ 命令行选项可以为单个命令启用或禁用升级调试模式。通过 [--v2-debug](https://docs.aws.amazon.com/cli//latest/userguide/cli-configure-options.html#cli-configure-options-v2-debug) 使用升级调试模式。
+ 环境变量使用 [AWS\$1CLI\$1UPGRADE\$1DEBUG\$1MODE](https://docs.aws.amazon.com/cli//latest/userguide/cli-configure-envvars.html#envvars-list-aws_cli_upgrade_debug_mode) 变量。
# 使用 AWS CLI v1 到 v2 迁移工具将 AWS CLI 版本 1 升级到 AWS CLI 版本 2
本主题介绍 AWS CLI v1 到 v2 迁移工具。
我们建议 AWS CLI 版本 1 的用户升级到 AWS CLI 版本 2，以便使用新功能以及增强性能。AWS CLI 版本 1 和 AWS CLI 版本 2 之间的行为有所不同，可能需要您更新脚本或命令来获得相同的行为。AWS CLI v1 到 v2 迁移工具分析包含 AWS CLI 版本 1 命令的 bash 脚本，并检测已通过 AWS CLI 版本 2 中的破坏性更改而更新的功能的使用情况。此外，该工具可以自动修改您的脚本，以修复它检测到的大多数问题。此工具通过自动检测和修改 bash 脚本中的 AWS CLI 版本 1 命令来改善升级体验，以防止在升级到版本 2 时出现意外问题。
与升级调试模式相比，AWS CLI v1 到 v2 迁移工具是一个独立工具，不需要执行 AWS CLI 命令。要全面比较升级调试模式和 AWS CLI v1 到 v2 迁移工具，请参阅 [AWS CLI 版本 2 的迁移指南](cliv2-migration.md)中的[使用 AWS CLI 迁移工具减少损坏](cliv2-migration.md#using-migration-tools)。
有关更多详细信息，请参阅 [AWS CLI 版本 2 中的新功能和变化](cliv2-migration-changes.md)中的 [AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)。
## 工作方式
AWS CLI v1 到 v2 迁移工具是一个 Python 软件包，能够分析使用 AWS CLI 版本 1 的 bash 脚本。作为一个静态 linter，它不依赖于您可能已在计算机上安装的 AWS CLI 版本 1 的版本。此 linter 通过命令行进行调用，其中 bash 脚本的本地文件路径作为参数提供。
此迁移工具还可以自动生成修改后的 bash 脚本，该脚本通过修改脚本中使用的 AWS CLI 版本 1 命令来解决它检测到的大部分调查发现。迁移工具修改命令，以便它们与 AWS 版本 2 兼容，并保留版本 1 的行为。
对于某些调查发现，AWS CLI v1 到 v2 迁移工具可以检测到它们，但不提供自动修复。在这些情况下，迁移工具会将其标记为需要手动审核的检测结果。
有关 AWS CLI v1 到 v2 迁移工具支持的破坏性更改和自动修复的详尽列表，请参阅[限制](#migration-tool-limitations)。
## 先决条件
### Python
要使用此工具，您必须已安装 Python 3.9 或更高版本。
要验证您安装的 Python 版本是否正确，请在终端中运行以下命令，并确认输出显示的 Python 版本至少为 3.9。
```
$ python3 --version
```
如果您使用的是较旧的 Python 版本，或者没有安装 Python，则可以从[官方 Python 下载页面](https://www.python.org/downloads/)下载兼容版本。
### pip
除了安装 Python 的兼容版本之外，您还必须安装了 `pip`。
要验证是否安装了 `pip`，请运行以下命令：
```
$ python3 -m pip --version
```
如果安装了 `pip`，您将看到类似于以下内容的输出：
```
pip 25.0.1 from ~/.local/lib/python3.13/site-packages (python 3.13)
```
如果您尚未安装 `pip`，请参阅[安装 pip](https://docs.aws.amazon.com/cli/v1/userguide/install-linux.html#install-linux-pip-pip)。
## 安装
在新的虚拟环境中安装 AWS CLI v1 到 v2 迁移工具：
```
$ python3 -m venv .venv
$ source .venv/bin/activate
$ python3 -m pip install aws-cli-migrate
```
## 用法
### 试运行模式（默认）
在试运行模式下，您无需修改输入脚本，即可自动检测会发生破坏性更改的 AWS CLI 版本 1 命令：
```
$ migrate-aws-cli --script upload_s3_files.sh
```
### 自动修复模式
在自动修复模式下，您可以在可能的情况下自动检测和更新输入脚本中的 AWS CLI 版本 1 命令，以缓解因 AWS CLI 版本 2 中引入的更改造成的损坏：
```
$ migrate-aws-cli --script upload_s3_files.sh --fix
```
或者，您可以通过 `--output` 参数提供输出路径来写入更新的脚本，而不是更新输入脚本：
```
$ migrate-aws-cli --script upload_s3_files.sh --output upload_s3_files_v2.sh --fix
```
### 交互模式
在交互模式下，您可以自动检测会发生破坏性更改的 AWS CLI 版本 1 命令。大多数调查发现将显示建议的修复，以缓解 AWS CLI 版本 2 中的损坏。您可以查看建议的修复并决定是否应用它们。或者，通过 `--output` 参数提供输出路径，以控制将更新的脚本写入何处：
```
$ migrate-aws-cli --script upload_s3_files.sh --interactive \
--output upload_s3_files_v2.sh
```
以下输出代码段是交互模式下的调查发现示例：
```
14 14│
15 15│ aws s3 ls s3://mybucket
16 16│
17 │-aws s3 cp s3://amzn-demo-bucket s3://amzn-demo-bucket2 --recursive
17│+aws s3 cp s3://amzn-demo-bucket s3://amzn-demo-bucket2 --recursive --copy-props none
18 18│
19 19│ TEMPLATE_KEY="cloudformation/$(basename "$TEMPLATE_FILE")"
20 20│
examples/upload_s3_files.sh:17 [s3-copy] In AWS CLI v2, object properties will be copied
from the source in multipart copies between S3 buckets. If a copy is or becomes multipart
after upgrading to AWS CLI v2, extra API calls will be made. See
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-s3-copy-metadata.
Apply this fix? [y] yes, [n] no, [a] accept all of type, [r] reject all of type, [u] update all,
[s] save and exit, [q] quit:
```
建议的修复以类似于 Git 差异的格式显示。迁移工具建议移除以 `-` 开头的行，并建议添加以 `+` 开头的行。在前面的示例中，建议可以解释为将 `--copy-props none` 参数添加到执行 Amazon S3 副本的 AWS CLI 版本 1 命令中。
对于每个建议的修复，您可以输入以下任何控件：
+ 输入 `y` 以接受建议的修复。
+ 输入 `n` 以拒绝当前修复。
+ 输入 `a` 以接受所有相同类型的修复。
+ 输入 `r` 以拒绝所有相同类型的修复。
+ 输入 `u` 以接受所有剩余的修复。
+ 输入 `s` 以保存并退出。
+ 输入 `q` 以退出而不保存。
有些调查发现可能会标记为需要手动审核，而没有建议的修复。您应该审核这些调查发现，并验证您是否受到所提到的破坏性更改的影响。如果您受到这些调查发现的影响，则应按照调查发现描述中指定的指导进行必要的更改，以避免 AWS CLI 版本 2 中引入的破坏性更改或相应地做好准备。
## 限制
AWS CLI v1 到 v2 迁移工具目前并不支持 AWS CLI 版本 2 中引入的每项破坏性更改，并且存在误报情况，即使实际上不会面临任何破坏性更改，它也会输出命令的检测结果。
我们强烈建议客户了解 [AWS CLI 版本 2 中的新功能和变化](cliv2-migration-changes.md)中发布的 [AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)。
### 基于文本的分析
迁移工具无需运行脚本即可分析该脚本。这限制了它检测 AWS CLI 命令是否存在破坏性更改的方式。此迁移工具只能检查 AWS CLI 命令的文本。它无法检测运行时出现的问题，例如将已弃用的参数存储在变量中，而不是将其直接传递给 AWS CLI。
### 不支持的破坏性更改检测
下表汇总了对迁移工具中破坏性更改的支持程度。
| 破坏性更改 | 支持检测 | 支持自动修复 |
| --- | --- | --- |
| [添加了用于设置文本文件编码的环境变量](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | 否 | 否 |
| [原定设置情况下，二进制参数作为 base64 编码字符串进行传递](cliv2-migration-changes.md#cliv2-migration-binaryparam) | 是 | 是 |
| [改进了执行分段复制时 Amazon S3 处理文件属性和标签的方式](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | 是 | 是 |
| [不自动检索 `http://` 或 `https://` URL 以获取参数](cliv2-migration-changes.md#cliv2-migration-paramfile) | 否 | 否 |
| [原定设置情况下，使用分页程序处理所有输出](cliv2-migration-changes.md#cliv2-migration-output-pager) | 是 | 是 |
| [时间戳输出值标准化为 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) | 否 | 否 |
| [改进了 CloudFormation 部署的处理，而这不会导致任何更改](cliv2-migration-changes.md#cliv2-migration-cfn) | 是 | 是 |
| [更改了区域 Amazon S3 端点对于 `us-east-1` 区域的原定设置行为](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | 否 | 否 |
| [已更改区域 AWS STS 端点的原定设置行为](cliv2-migration-changes.md#cliv2-migration-sts-regional-endpoint) | 否 | 否 |
| [`ecr get-login` 已删除并替换为 `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | 是 | 否 |
| [AWS CLI 版本 2 对插件的支持会不断变化](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | 否 | 否 |
| [已删除隐藏别名支持](cliv2-migration-changes.md#cliv2-migration-aliases) | 是 | 是 |
| [不支持 `api_versions` 配置文件设置](cliv2-migration-changes.md#cliv2-migration-api-versions) | 否 | 否 |
| [AWS CLI 版本 2 仅使用签名 v4 对 Amazon S3 请求进行身份验证](cliv2-migration-changes.md#cliv2-migration-sigv4) | 否 | 否 |
| [AWS CLI 版本 2 与分页参数更一致](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 是 | 否 |
| [AWS CLI 版本 2 在所有命令间提供了更一致的返回代码](cliv2-migration-changes.md#cliv2-migration-return-codes) | 否 | 否 |