使用升级调试模式将 AWS CLI 版本 1 升级到 AWS CLI 版本 2 - AWS Command Line Interface
工作原理限制配置升级调试模式

使用升级调试模式将 AWS CLI 版本 1 升级到 AWS CLI 版本 2

我们建议 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 版本 1 和 AWS CLI 版本 2 之间的突破性更改。

从 AWS CLI 版本 1 升级到版本 2 时，可能会遇到影响现有脚本和工作流的AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改。升级调试模式可帮助您在完成迁移之前识别这些问题。

当您使用在 AWS CLI 版本 2 中具有突破性更改的功能时，升级调试模式会检测到这些问题。当您运行一个在升级后会出问题的命令时，该模式会显示警告，并提供具体的问题解决步骤。这样可以自动查找潜在问题，而不是手动搜索代码，从而节省您的时间。

工作原理

如果启用升级调试模式，该模式会检测在 AWS CLI 版本 2 中有突破性更改的更新功能的使用情况。如果您在升级到 AWS CLI 版本 2 后使用我们的 AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改中列出的命令或功能，则输出中将会显示一条警告。突破性更改检测基于所使用的命令、提供的参数、执行环境（例如环境变量、配置设置等），并且在某些情况下，还基于所使用的 AWS 账户中资源的内容或配置。

下面的示例演示了这些警告的具体形式。此命令演示一个警告示例。所有警告文本都以“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 行为
添加了用于设置文本文件编码的环境变量 取消设置 PYTHONUTF8 和 PYTHONIOENCODING 环境变量。 将 AWS_CLI_FILE_ENCODING 环境变量设置为 v1 中指定的编码。
原定设置情况下，二进制参数作为 base64 编码字符串进行传递 使用 base64 对参数的值进行编码。如果该参数是从文件加载的，则使用 base64 对文件内容进行编码。 将 cli_binary_format 设置为 raw-in-base64-out。
改进了执行分段复制时 Amazon S3 处理文件属性和标签的方式 不适用。无法在版本 1 中迁移到版本 2 行为。 使用 --copy-props none 参数。
不自动检索 http:// 或 https:// URL 以获取参数 使用 curl（或替代工具）将 URL 的内容下载到本地文件。然后，使用 file:// 将文件内容加载到该参数中。或者，将 cli_follow_urlparam 配置为 false 以将原始 URL 指定为参数值。 不适用。无法在版本 2 中保留版本 1 行为。
原定设置情况下，使用分页程序处理所有输出 不适用。无法在版本 1 中迁移到版本 2 行为。 将 cli_pager 设置或 AWS_PAGER 变量设定为空字符串。
时间戳输出值标准化为 ISO 8601 格式 将 cli_timestamp_format 设置为 iso8601。 将 cli_timestamp_format 设置为 wire。
改进了 CloudFormation 部署的处理，而这不会导致任何更改 使用 --no-fail-on-empty-changeset 参数。 使用 --fail-on-empty-changeset 参数。
更改了区域 Amazon S3 端点对于 us-east-1 区域的原定设置行为 将 AWS_ENDPOINT_URL_S3 环境变量或 --endpoint-url 命令行选项设置为 us-east-1 区域 URL。 使用 --region aws-global 命令行选项。
ecr get-login 已删除并替换为 ecr get-login-password （1.17.10 或更高版本）使用 ecr get-login 已删除并替换为 ecr get-login-password 并将输出通过管道传输到 docker 命令。 不适用。无法在版本 2 中保留版本 1 行为。
AWS CLI 版本 2 对插件的支持会不断变化 不适用。无法在版本 1 中迁移到版本 2 行为。 将 cli_legacy_plugin_path 配置到配置文件的 [plugins] 部分中。在版本 2 中测试插件，锁定版本 2 的版本，并在每次升级时测试您的插件。
已删除隐藏别名支持 从使用过时的隐藏别名切换为已删除隐藏别名支持，这种方式在所有版本中都能正常工作。 不适用。无法在版本 2 中保留版本 1 行为。
不支持 api_versions 配置文件设置 将您使用的旧版本 API 迁移到最新的 API 版本并进行测试，然后从您的配置设置中移除 api_versions。 不适用。无法在版本 2 中保留版本 1 行为。
AWS CLI 版本 2 仅使用签名 v4 对 Amazon S3 请求进行身份验证 将签名版本指定为版本 4（参见在请求身份验证中指定签名版本）。 不适用。无法在版本 2 中保留版本 1 行为。
AWS CLI 版本 2 与分页参数更一致 将输入 JSON 参数中的分页参数移到命令本身。 从输入 JSON 参数中移除分页参数。
AWS CLI 版本 2 在所有命令间提供了更一致的返回代码 不适用。无法在版本 1 中迁移到版本 2 行为。 不适用。无法在版本 2 中保留版本 1 行为。

限制

我们强烈建议客户查看我们的 AWS CLI 版本 1 和 AWS CLI 版本 2 之间的突破性更改。

不支持的突破性更改检测

升级调试模式功能支持除 AWS CLI 版本 2 在所有命令间提供了更一致的返回代码之外的所有突破性更改。此模式无法处理您使用 AWS CLI 下游所返回错误代码的方式。

有条件的突破性更改检测

时间戳输出值标准化为 ISO 8601 格式的检测是检测依赖于 AWS 账户状态的唯一情况，如果账户资源以后发生更新，可能会出现突破性更改。如果服务的 API 响应中不包含时间戳，则不会针对此突破性更改进行任何检测。

如果您依赖于 AWS CLI 命令返回的时间戳格式，并且尚未将 AWS CLI 配置为使用 ISO 8601，请格外小心，以确保在升级到版本 2 后时间戳处理过程不会出错。

无法解决的突破性更改检测

升级调试模式输出的一些警告无法通过修改命令或环境来解决。在以下情况下，只要您使用相应的功能，升级调试模式就会始终输出警告：

误检测

升级调试模式输出的警告并不能保证升级到 AWS CLI v2 后会遇到突破性更改。在以下情况下，即使在 AWS CLI v2 中没有引入突破性更改，升级调试模式仍会输出警告：

配置升级调试模式

您可以使用以下按优先顺序列出的方法启用或禁用升级调试模式：