View a markdown version of this page

开始使用 AWS 变换自定义 - AWS 转换
选择跑步地点 AWS 变换自定义AWS 转换 CLI 先决条件安装   AWS 转换 CLI配置身份验证配置 AWS Region运行你的第一次转型了解转换结果创建自定义转换AWS 转换 Web 应用程序（可选）

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

开始使用 AWS 变换自定义

本节介绍如何选择接口、设置 Trans AWS form custom 以及如何运行第一次转换。

选择跑步地点 AWS 变换自定义

AWS 通过命令行、Kiro Power、代理插件或 IDE 插件运行 Transform custom。每个选项都提供对相同 AWS托管和自定义转换定义的访问权限。

重要

推荐用于引导式设置：使用 Kiro Power 或 AWS 变换代理插件。在安装过程中，代理会检查先决条件，并在需要时安装或更新 T AWS ransform CLI。然后，它会引导你完成第一次转换。您仍然需要适当的 AWS 权限和对要转换的存储库的访问权限。

AWS Transform CLI

使用 T AWS ransform CLI 进行终端工作流程、脚本和自动化。使用此选项，您可以手动完成设置。那么AWS 转换 CLI 先决条件，请查看安装   AWS 转换 CLI。

Kiro Power

使用 T AWS ransform Kiro Power 在 Kiro IDE 中进行引导式对话式工作流程。

  1. 打开 Kiro IDE 并导航到 “电源” 面板。

  2. 找到 T AWS ransform 并安装它。

  3. 打开 Kiro Chat，选择 Power，然后选择 T ry power。

安装后，让 Kiro 设置 Trans AWS form custom，并向你展示仓库中可用的变换。

有关 GitHub 导入选项和身份验证信息，请参见Kiro 能力。

Agent plugin

在要 AWS 转换的存储库中使用 Claude Code、Codex 或 Cursor 的 Transform 代理插件。

在 Claude Code 中安装

添加 AWS 代理插件市场并安装 Tr AWS ansform 插件：

/plugin marketplace add awslabs/agent-plugins
/plugin install aws-transform@agent-plugins-for-aws
在 Codex 或 Cursor 中安装

按照网站上代理插件存储库 README 中的安装说明进行操作。 GitHub 有关更多信息，请参阅 代理插件。

安装后，请您的编码代理设置 Trans AWS form custom，并向您展示存储库中可用的转换。

IDE plugin

使用 Trans AWS form IDE 插件从 VS Code 或兼容 Open VSX 的编辑器中创建和运行转换定义。

有关更多信息，请参阅 IDE 插件。

如果您选择了 Trans AWS form CLI，请继续执行接下来的 CLI 先决条件。如果您选择了其他选项，请按照所选选项卡中的设置说明进行操作。

要集中监控跨多个存储库的转型活动，请参阅AWS 转换 Web 应用程序（可选）。

AWS 转换 CLI 先决条件

在安装 T AWS ransform custom 之前，请确保您具备以下条件：

支持的平台

AWS 自定义转换支持以下操作系统：

  • Linux-完全支持所有 Linux 发行版

  • macOS-全面支持 macOS 系统

  • Windows-完全支持使用 Windows 终端的本机 Windows 和 PowerShell （Windows 尚不支持这些atx ct命令）

  • 适用于 Linux 的 Windows 子系统 (WSL)-在 WSL 下运行时支持

必需的软件

  • Node.js 22 或更高版本-从中下载 https://nodejs.org/en/download

  • Git-必须安装并且工作目录必须是有效的 Git 存储库才能执行转换。运行git init; git add .; git commit -m "Initial commit"以初始化工作目录中的 Git 存储库。

网络要求

需要能够访问以下端点的互联网连接：

  • transform-cli.awsstatic.com

  • transform-custom.<region>.api.aws

  • *.s3.amazonaws.com

如果您在受互联网限制的环境中工作，请更新防火墙规则以将这些 URL 列入许可名单。

安装   AWS 转换 CLI

推荐的安装方法是使用安装脚本。选择与您的操作系统对应的选项卡。

安装 Trans AWS form CLI

  1. 运行安装脚本：

    Linux and macOS
    curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash
    Windows (PowerShell)

    在本机 Windows 上，使用从 Windows 终端运行安装脚本 PowerShell。

    irm https://transform-cli.awsstatic.com/install.ps1 | iex

  2. 验证安装：

    atx --version

    该命令应显示已安装的 Trans AWS form CLI 版本。

配置身份验证

AWS 转换自定义需要 AWS 凭据才能使用服务进行身份验证。使用以下方法之一配置身份验证。

环境变量

设置以下环境变量。

Linux and macOS
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_SESSION_TOKEN=your_session_token
Windows (PowerShell)
$env:AWS_ACCESS_KEY_ID="your_access_key"
$env:AWS_SECRET_ACCESS_KEY="your_secret_key"
$env:AWS_SESSION_TOKEN="your_session_token"

您也可以使用AWS_PROFILE环境变量指定配置文件。

Linux and macOS
export AWS_PROFILE=your_profile_name
Windows (PowerShell)
$env:AWS_PROFILE="your_profile_name"
注意

$env:中设置的环境变量仅 PowerShell 适用于当前会话。要在会话中保留它们，请通过 “系统属性” > “环境变量” 进行设置，或者使用[System.Environment]::SetEnvironmentVariable()。

AWS 凭证文件

在证书文件中配置 AWS 凭据，该文件位于 Linux 和 macOS ~/.aws/credentials 上，或者%USERPROFILE%\.aws\credentials在 Windows 上：

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key

IAM 权限

您的 AWS 证书必须具有调用 Trans AWS form 自定义服务的权限。我们建议将AWSTransformCustomFullAccess AWS 托管策略附加到您的 IAM 用户或角色。此政策提供对 Trans AWS form custom 的完全访问权限，包括创建向账户发布 CloudWatch 指标所需的服务相关角色的权限。

为了实现更精细的控制，Trans AWS form custom 还提供了以下 AWS 托管策略：

有关这些策略的更多信息，请参阅 Trans AWS form 的AWS 托管策略。有关具有资源级权限的自定义 IAM 策略，请参阅AWS 转换自定义 IAM 服务授权参考指南。

注意

  • 转换定义是带有 ARN 的 AWS 资源（Amazon 资源名称）。通过在 IAM 策略资源声明中指定转换 ARN，您可以使用 IAM 策略来控制对特定转换或转换组的访问权限。标签可用于分组访问控制。

  • AWS 需要使用 IAM 身份中心才能访问 AWS 转换，但不需要使用 CLI。

配置 AWS Region

AWS Transform custom 可在特定 AWS 区域使用，并使用标准 AWS CLI 优先级自动检测您的区域配置。

支持的区域：

AWS 自定义转换在以下 AWS 区域可用：

  • us-east-1（美国东部-弗吉尼亚北部）

  • eu-central-1（欧洲-法兰克福）

  • eu-west-2（欧洲-伦敦）

  • ca-central-1（加拿大-中部）

  • ap-northeast-1（亚太地区-东京）

  • ap-northeast-2（亚太地区-首尔）

  • ap-southeast-2（亚太地区-悉尼）

  • ap-south-1（亚太地区-孟买）

如何确定区域

CLI 按优先顺序检查这些来源，以确定要使用哪个区域：

  1. AWS_REGION环境变量（最高优先级）

  2. AWS_DEFAULT_REGION 环境变量

  3. 配置文件中选定的 AWS 配置文件（通过AWS_PROFILE环境变量）

  4. 配置文件中的默认 AWS 配置文件

  5. us-east-1如果未找到配置，则默认回退为

注意

AWS 配置文件位于 Linux 和 macOS ~/.aws/config 上，或者位于 Windows %USERPROFILE%\.aws\config 上。

注意

如果ATX_CUSTOM_ENDPOINT已设置，则从终端节点 URL 中提取该区域并覆盖所有其他设置。

设置您的区域

选择以下方法之一来配置您的区域：

选项 1：环境变量（建议临时使用）：

Linux and macOS
export AWS_REGION=<your-region>
Windows (PowerShell)
$env:AWS_REGION="<your-region>"

选项 2： AWS CLI 配置（建议永久设置使用）：

aws configure set region <your-region>

选项 3： Profile-specific 配置：

Linux and macOS
aws configure set region <your-region> --profile your_profile_name
export AWS_PROFILE=your_profile_name
Windows (PowerShell)
aws configure set region <your-region> --profile your_profile_name
$env:AWS_PROFILE="your_profile_name"

选项 4：直接编辑文件：

直接编辑 AWS 配置文件（在 Linux 和 macOS ~/.aws/config 上，或者%USERPROFILE%\.aws\config在 Windows 上）：

[default]
region = <your-region>

[profile your_profile_name]
region = <your-region>

验证您的区域配置

要检查 AWS 变换自定义将使用哪个区域，请执行以下操作：

检查当前区域设置：

aws configure get region

检查环境变量：

Linux and macOS
echo "AWS_REGION: $AWS_REGION"
echo "AWS_DEFAULT_REGION: $AWS_DEFAULT_REGION"
echo "AWS_PROFILE: $AWS_PROFILE"
Windows (PowerShell)
echo "AWS_REGION: $env:AWS_REGION"
echo "AWS_DEFAULT_REGION: $env:AWS_DEFAULT_REGION"
echo "AWS_PROFILE: $env:AWS_PROFILE"

在调试日志中查看详细的区域解析：

Linux and macOS
tail -f ~/.aws/atx/logs/debug.log
Windows (PowerShell)
Get-Content "$env:USERPROFILE\.aws\atx\logs\debug.log" -Wait -Tail 10

显示区域来源的日志输出示例：

2026-01-07 22:34:28 [DEBUG]: Initializing FrontendServiceClient with config:
{
  "endpoint": "https://transform-custom.us-east-1.api.aws",
  "region": "us-east-1",
  "regionSource": "AWS_REGION"
}

该regionSource字段显示该区域的来源（例如，“aws-config（配置文件：默认）”、“AWS_REGION”、“默认”）。

重要

如果您的区域配置指向不支持的区域，CLI 将显示一条明确的错误消息，说明如何将您的配置更新到支持的区域。

运行你的第一次转型

最快的入门方法是使用 AWS托管转换。 AWS-managed 转换是预先构建的、 AWS经过审查的转换，无需任何设置即可使用。

要以交互方式运行 AWS托管转换，请执行以下操作：

atx

然后让代理执行转换：

Execute the AWS/java-aws-sdk-v1-to-v2 transformation on the codebase at ./my-java-project

要以非交互方式运行转换，请执行以下操作：

atx custom def exec -n AWS/java-aws-sdk-v1-to-v2 -p ./my-java-project -c "mvn clean install" -x -t

有关执行模式、配置选项和命令标志的详细信息，请参见Command Reference。

了解转换结果

转换完成后，Trans AWS form custom 会提供一份描述结果的报告。如果转换未经过验证（例如，成功构建 Java 应用程序），则报告将提供进一步操作的建议。

大多数转换都是分多个步骤执行的，使用 Git 提交中间步骤。您可以使用标准 Git 命令查看转换所做的更改：

git status
git log
git diff <original commit-id>

创建自定义转换

当 AWS托管转换不能满足您的需求时，您可以根据您的特定要求创建自定义转换。

创建自定义转换

  1. 在交互模式下 AWS 启动 Transform CLI：

    atx

  2. 告诉代理您要创建新的转换并描述您的要求。

  3. 提供参考资料，例如文档和代码样本以提高质量。

  4. 反复测试和完善转换。

  5. 将其发布到您组织的转型注册表。

有关创建自定义转换的详细说明，请参阅工作流。

AWS 转换 Web 应用程序（可选）

Trans AWS form Web 应用程序是一个可选界面，用于监控跨多个存储库的大规模转型活动。在使用 T AWS ransform Web 应用程序之前，您需要启用用户身份才能在组织中访问 T AWS ransform。有关启用 AWS 转换的信息，请参阅设置 AWS 转换。

要使用 AWS 转换 Web 应用程序，请执行以下操作：

  1. 使用 AWS IAM 身份中心证书访问https://aws.amazon.com/transform/并登录。

  2. 在 T AWS ransform Web 应用程序中选择 “自定义/代码” 作业类型。

  3. 告诉代理您要使用的转换定义的名称。

  4. Web 应用程序提供了可以与您的团队共享的 Transf AWS orm CLI 命令。此命令调用转换定义并将执行结果记录到 Web 应用程序。

  5. 捕获转换结果后，在控制面板中查看统计数据、节省时间的衡量标准，并询问有关工作进度的问题。

Web 应用程序专为企业级操作而设计，在这些操作中，您需要集中监控多个代码库中的转换。

注意

AWS 需要使用 IAM 身份中心才能访问 Trans AWS form Web 应用程序。CLI 不需要 IAM 身份中心，只需要标准 AWS 证书。