# 使用升级调试模式将 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) 变量。