# Amazon CLI 版本 2 的迁移指南
<a name="cliv2-migration"></a>

本节包含将 Amazon CLI 版本 1 更新为 Amazon CLI 版本 2 的说明。Amazon CLI 版本 2 建立在 Amazon CLI 版本 1 的基础上，包括基于社区反馈的功能和增强功能。Amazon CLI 版本 2 是 Amazon CLI 的最新主版本，支持所有最新功能。版本 2 中引入的某些功能未向后移植到版本 1，您必须升级才能访问这些功能。

为防止出现意外问题，在迁移至版本 2 之前，请[了解这两个版本之间的区别](cliv2-migration-changes.md)。Amazon CLI 版本 2 包括的新功能和更改可能要求您更新脚本或命令以实现向后兼容性。

Amazon CLI 版本 1 和 2 使用相同的 `aws` 命令名称。如果您安装了两个版本，电脑将使用在搜索路径中找到的第一个版本。这可能会导致您的 `aws` 命令名调用旧 Amazon CLI 版本，即使您安装了新版本也是如此。

要更新到 Amazon CLI 版本 2，请按照以下说明之一进行操作：
+ 如果您之前安装了 Amazon CLI 版本 1，请按照[从 Amazon CLI 版本 1 安装 Amazon CLI 版本 2](cliv2-migration-instructions.md)中的说明操作。
+ 如果您之前未安装 Amazon CLI 版本 1，请按照[开始使用 Amazon CLI](cli-chap-getting-started.md)中的说明操作。

## 使用 Amazon CLI 迁移工具减少损坏
<a name="using-migration-tools"></a>

Amazon CLI 版本 1 和 Amazon CLI 版本 2 之间的行为有所不同，这可能需要您更新脚本或命令。在不验证现有脚本是否已安全迁移的情况下升级到 Amazon CLI 版本 2，可能会在使用 Amazon CLI 版本 2 运行脚本时遭遇意外影响，例如对 Amazon 账户中的资源进行意外的更改。

您可以使用两种 Amazon 拥有的工具来指导迁移。无论您使用哪种工具，我们都建议您参考 [Amazon CLI 版本 2 中的新功能和变化](cliv2-migration-changes.md)指南中的 [Amazon CLI 版本 1 和 Amazon CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)。

### 升级调试模式
<a name="cliv2-migration-upgrade-debug-mode"></a>

升级调试模式是 Amazon CLI 版本 1 中的一项功能，在版本 `1.44.0` 及更高版本中可用。启用此功能后，假设执行环境保持不变，则系统会检查您执行的每个 Amazon CLI 命令，以确定它在 Amazon CLI 版本 2 中是否可能有不同的行为。如果执行的命令在 Amazon CLI 版本 2 中具有不同的行为，则命令输出旁边将显示一条警告，其中包含建议的操作，可以采取这些操作在 Amazon CLI 版本 2 中保留 Amazon CLI 版本 1 行为。

使用升级调试模式来指导迁移的主要原因是，此模式具有很高的覆盖范围，可以检测命令是否会面临行为变化。[Amazon CLI 版本 1 和 Amazon CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)中描述的 15 个破坏性更改中有 14 个可以在升级调试模式下检测到。有关此功能的局限性，请参阅[使用升级调试模式将 Amazon CLI 版本 1 升级到 Amazon CLI 版本 2](cli-upgrade-debug-mode.md) 中的[限制](cli-upgrade-debug-mode.md#upgrade-mode-limitations)。另一方面，使用升级调试模式的主要缺点是其输出仅在其执行环境中相关；如果迁移到 Amazon CLI 版本 2 后，环境中的任何 Amazon CLI 配置设置发生变化，则仍可能发生破坏性更改，而您应该在更新后的环境中使用升级调试模式进行重新验证。

### Amazon CLI v1 到 v2 迁移工具
<a name="cliv2-migration-migration-tool"></a>

Amazon CLI v1 到 v2 迁移工具是一个独立的工具，可以与 Python 3.9 及更高版本一起使用。此工具是一个独立于 Amazon CLI 运行的静态 linter。它会检查包含 Amazon CLI 版本 1 命令的 bash 脚本，这些命令在 Amazon CLI 版本 2 中可能具有不同的行为。对于它检测到在 Amazon CLI 版本 2 中可能具有不同行为的大多数命令，它可以自动更新脚本中的命令，以便在 Amazon CLI 版本 2 中保留 Amazon CLI 版本 1 行为。

使用 Amazon CLI v1 到 v2 迁移工具来指导迁移的主要原因是，它可以自动更新您的脚本，以便在 Amazon CLI 版本 2 中保留 Amazon CLI 版本 1 行为，从而节省您自行进行更新的时间和精力。另一方面，使用迁移工具的主要缺点是，它检测命令是否会面临行为变化的覆盖范围较小。作为一个静态工具，它不检查在运行时确定的行为变化。

## 在升级调试模式与 Amazon CLI v1 到 v2 迁移工具之间进行选择
<a name="cliv2-migration-choosing-migration-tool"></a>

下表重点介绍了升级调试模式与 Amazon CLI v1 到 v2 迁移工具之间的主要区别，可用于协助指导您为自己的使用案例选择正确的工具。


| 升级调试模式 | Amazon CLI v1 到 v2 迁移工具 | 
| --- | --- | 
| 检测 Amazon CLI 版本 1 和 Amazon CLI 版本 2 之间的 15 个破坏性更改中的 14 个。 | 检测 Amazon CLI 版本 1 和 Amazon CLI 版本 2 之间的 15 个破坏性更改中的 7 个。 | 
| 与任何可以运行 Amazon CLI 的终端程序兼容。 | 仅支持检查 bash 脚本。 | 
| 需要 Amazon CLI 版本 1、版本 1.44.0 或更高版本。 | 独立于 Amazon CLI 运行；它不要求安装 Amazon CLI。 | 
| 必须进行手动修复，才能在 Amazon CLI 版本 2 中保留 Amazon CLI 版本 1 行为。 | 自动修复它检测到的大多数 Amazon CLI 版本 1 命令，这些命令在 Amazon CLI 版本 2 中可能有不同的行为。 | 
| 检测结果和建议的修复仅与执行它的执行环境（即 Amazon CLI 配置）有关。 | 检测结果和建议的修复与环境无关。 | 
| 需要执行每条被测的 Amazon CLI 命令以了解行为变化。 | 不需要执行任何 Amazon CLI 命令。对于每个 bash 脚本只需要执行一次。 | 
| 正好有 5 个它将输出误报检测结果的已知情况。 | 正好有 3 个它将输出误报检测结果的已知情况。 | 

下表显示了这两个迁移工具中的每一个工具支持哪些 [Amazon CLI 版本 1 和 Amazon CLI 版本 2 之间的突破性更改](cliv2-migration-changes.md#cliv2-migration-changes-breaking)。


| 破坏性更改 | 由升级调试模式检测到 | 由 Amazon 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) | 是 | 否 | 
| [已更改区域 Amazon 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) | 是 | 是 | 
| [Amazon 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) | 是 | 否 | 
| [Amazon CLI 版本 2 仅使用签名 v4 对 Amazon S3 请求进行身份验证](cliv2-migration-changes.md#cliv2-migration-sigv4) | 是 | 否 | 
| [Amazon CLI 版本 2 与分页参数更一致](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 是 | 是 | 
| [Amazon CLI 版本 2 在所有命令间提供了更一致的返回代码](cliv2-migration-changes.md#cliv2-migration-return-codes) | 否 | 否 | 

## 此部分中的其他主题
<a name="migrate-topics"></a>
+ [Amazon CLI 版本 2 中的新功能和变化](cliv2-migration-changes.md)
+ [从 Amazon CLI 版本 1 安装 Amazon CLI 版本 2](cliv2-migration-instructions.md)
+ [使用升级调试模式将 Amazon CLI 版本 1 升级到 Amazon CLI 版本 2](cli-upgrade-debug-mode.md)
+ [使用 Amazon CLI v1 到 v2 迁移工具将 Amazon CLI 版本 1 升级到 Amazon CLI 版本 2](cli-migration-tool.md)