View a markdown version of this page

開始使用 - AWS 轉換
先決條件安裝 AWS 轉換 CLI設定身分驗證設定 AWS 區域執行您的第一個轉換了解轉換結果建立自訂轉換AWS 轉換 Web 應用程式 （選用）

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

開始使用

本節說明如何設定 AWS 轉換自訂並執行您的第一個轉換。

先決條件

在安裝 AWS 轉換自訂之前，請確定您有下列項目：

支援的平台

AWS 轉換自訂支援下列作業系統：

  • Linux - 完整支援所有 Linux 發行版本

  • macOS - macOS 系統的完整支援

  • Windows - 使用 Windows Terminal 和 PowerShell 完整支援原生 Windows (Windows 尚未支援這些atx ct命令）

  • 適用於 Linux 的 Windows 子系統 (WSL) - 在 WSL 下執行時支援

必要軟體

  • Node.js 22 或更新版本 - 從 https：//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

如果您在限制網際網路的環境中工作，請更新防火牆規則以允許列出這些 URLs。

安裝 AWS 轉換 CLI

建議的安裝方法使用 安裝指令碼。選擇作業系統的索引標籤。

安裝 AWS 轉換 CLI

  1. 執行安裝指令碼：

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

    在原生 Windows 上，使用 PowerShell 從 Windows 終端機執行安裝指令碼。

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

  2. 驗證安裝：

    atx --version

    命令應會顯示 AWS Transform 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"
注意

在 PowerShell $env:中使用 設定的環境變數僅適用於目前的工作階段。若要跨工作階段保留它們，請透過系統屬性 > 環境變數進行設定，或使用 [System.Environment]::SetEnvironmentVariable()。

AWS 登入資料檔案

在登入資料檔案中設定 AWS 登入資料，位於 Linux 和 macOS ~/.aws/credentials 上的 ，或位於 Windows %USERPROFILE%\.aws\credentials上的 ：

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key

IAM 許可

您的 AWS 登入資料必須具有呼叫 AWS 轉換自訂服務的許可。建議您將 AWSTransformCustomFullAccess AWS 受管政策連接至 IAM 使用者或角色。此政策提供 AWS 轉換自訂的完整存取權，包括建立 CloudWatch 指標傳送至您的帳戶所需的服務連結角色的許可。

如需更精細的控制， AWS Transform 自訂也提供下列 AWS 受管政策：

如需這些政策的詳細資訊，請參閱 AWSAWS Transform 的 受管政策。如需具有資源層級許可的自訂 IAM 政策，請參閱 AWS 轉換自訂 IAM 服務授權參考指南。

注意

  • 轉換定義是具有 ARNs(Amazon Resource Name) AWS 的資源。您可以使用 IAM 政策，在 IAM 政策資源陳述式中指定轉換 ARN，以控制對特定轉換或轉換群組的存取。標籤可用於分組存取控制。

  • AWS 存取 AWS 轉換需要 IAM Identity Center，但使用 CLI 不需要。

設定 AWS 區域

AWS 轉換自訂可在特定 AWS 區域使用，並使用標準 CLI AWS 優先順序自動偵測您的區域組態。

支援的區域

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 如果找不到組態，預設回復至

注意

組態檔案位於 Linux AWS 和 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：設定檔特定的組態：

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 (~/.aws/config在 Linux 和 macOS 或 Windows %USERPROFILE%\.aws\config上）：

[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 （設定檔： default)"、"AWS_REGION"、"default")。

重要

如果您的區域組態指向不支援的區域，CLI 會顯示明確的錯誤訊息，其中包含將組態更新為支援區域的指示。

執行您的第一個轉換

開始使用的最快方法是使用 AWS受管轉換。 AWS受管轉換是預先建置、經過 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

如需執行模式、組態選項和命令旗標的詳細資訊，請參閱 命令參考。

了解轉換結果

當轉換完成時， AWS Transform 自訂會提供描述結果的報告。如果轉換未經過驗證 （例如，Java 應用程式的成功建置），則報告會提供進一步動作的建議。

大多數轉換都是以多個步驟執行，使用 Git 遞交中繼轉換。您可以使用標準 Git 命令檢閱轉換所做的變更：

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

建立自訂轉換

當 AWS受管轉換不符合您的需求時，您可以根據特定需求建立自訂轉換。

建立自訂轉換

  1. 在互動式模式下啟動 AWS 轉換 CLI：

    atx

  2. 告訴客服人員您要建立新的轉換並描述您的需求。

  3. 提供參考資料，例如文件和程式碼範例，以改善品質。

  4. 反覆測試和精簡轉換。

  5. 將其發佈到組織的轉換登錄檔。

如需建立自訂轉換的詳細說明，請參閱 工作流程。

AWS 轉換 Web 應用程式 （選用）

AWS 轉換 Web 應用程式是選擇性的界面，用於監控跨多個儲存庫的大規模轉換行銷活動。在使用 AWS 轉換 Web 應用程式之前，您需要啟用使用者身分，才能存取組織中的 AWS 轉換。如需啟用 AWS 轉換的資訊，請參閱設定 AWS 轉換。

若要使用 AWS 轉換 Web 應用程式：

  1. 請造訪 https://aws.amazon.com/transform/：// 並使用 AWS IAM Identity Center 登入資料登入。

  2. 在 AWS 轉換 Web 應用程式中選取「自訂/程式碼」任務類型。

  3. 告訴客服人員您要使用的轉換定義名稱。

  4. Web 應用程式提供 AWS Transform CLI 命令，可與您的團隊共用。此命令會叫用轉換定義，並將執行結果記錄到 Web 應用程式。

  5. 擷取轉換結果後，請在儀表板中檢視統計資料、節省時間測量，並詢問任務進度的問題。

Web 應用程式專為企業規模操作而設計，您需要集中監控跨多個程式碼庫的轉換。

注意

AWS 存取 AWS Transform Web 應用程式需要 IAM Identity Center。CLI 不需要 IAM Identity Center - 只需要標準 AWS 登入資料。