# 使用 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) | 否 | 否 |