對 的問題進行故障診斷 Amazon Q Developer Agent for code transformation - Amazon Q Developer
為什麼 Amazon Q 無法上傳我的專案？為什麼我的 Maven 命令失敗？如何將 Maven 新增至我的 PATH？為什麼 Amazon Q 無法建置我的程式碼？為什麼我的轉換在 55 分鐘後失敗？為什麼我無法下載轉換後的程式碼？如何存取程式碼轉換日誌？如何找到轉換任務 ID？

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

對 的問題進行故障診斷 Amazon Q Developer Agent for code transformation

下列資訊可協助您針對 的常見問題進行疑難排解 Amazon Q Developer Agent for code transformation.

為什麼 Amazon Q 無法上傳我的專案？

如果您的專案無法上傳，可能是下列其中一個問題所造成。請參閱與您在 Amazon Q 中看到的錯誤對應的主題。

減少專案大小

若要轉換程式碼，Amazon Q 會產生專案成品，其中包括原始程式碼、專案相依性和建置日誌。轉換任務的專案成品大小上限為 2 GB。如果您收到與專案成品大小相關的錯誤，則必須減少專案的大小，或嘗試轉換較小的專案。您可以在程式碼轉換日誌中檢視專案成品檔案的大小。如需詳細資訊，請參閱 如何存取程式碼轉換日誌？

在 中設定代理設定 IDE

若要轉換程式碼，Amazon Q 會將專案成品上傳到服務擁有的 Amazon S3 儲存貯體。上傳程序的一部分涉及使用 SSL或 TLS憑證來建立 Amazon S3 和 之間的通訊IDE。如果您使用的是代理伺服器，代理伺服器使用的 SSL或 TLS 憑證必須受信任，否則 Amazon Q 無法上傳您的專案。

如果您收到與代理或憑證相關的錯誤，您可能需要設定您的 IDE或 作業系統來信任您的憑證或更新其他代理設定。

注意

如果您位於組織的代理伺服器或防火牆後方，也可能會遇到與憑證無關的問題。如果您完成下列程序來設定憑證，但仍發生問題，請聯絡您的網路管理員，以確保您可從 與 Amazon S3 通訊IDE。如需詳細資訊，請參閱允許存取 Amazon S3。

在 中設定憑證 JetBrains

若要設定您的 JetBrains IDE Java Runtime Environment （JRE） 要信任代理伺服器使用的 SSL 或 TLS憑證，您必須將 SSL或 TLS憑證匯入 中的 cacerts 檔案JRE。cacerts 檔案是包含受信任根憑證的檔案，用於安全連線，例如 HTTPS和 SSL，而且它是 JRE安全設定的一部分。若要匯入憑證，請完成下列程序。

注意

我們建議您在修改cacerts檔案之前進行備份，因為任何錯誤都可能導致安全連線的問題。

  1. 判斷 中cacerts檔案的路徑JRE。您的 JRE隨附的內部 中的cacerts檔案路徑 JetBrains IDE 取決於作業系統和 的版本 JetBrains IDE 您正在使用。

    以下是常見作業系統中cacerts檔案的路徑範例。選擇您的作業系統以查看範例。

    注意

    <JetBrains Installation Folder> 是指 JetBrains 已安裝 產品。此目錄通常在安裝過程中選擇。

    jbr 資料夾代表與 JRE綁定的 JetBrains IDEs，這是為搭配 使用而JRE量身打造的特定 版本 JetBrains IDEs.

    Windows

    cacerts 的檔案路徑 JetBrains IDE Windows 上安裝的是：

    <JetBrains Installation Folder>\jbr\bin\cacerts

    例如，如果您安裝了 JetBrains IDE 在預設位置的 Windows 上，路徑可能是：

    C:\Program Files\JetBrains\jbr\bin\cacerts
    macOS

    cacerts 的檔案路徑 JetBrains IDE macOS 上安裝的是：

    /Applications/JetBrains Toolbox/<version>/JetBrains Toolbox.app/Contents/jbr/Contents/Home/lib/security/cacerts

    例如，如果您安裝了 JetBrains IDE 在預設位置的 macOS 上，路徑可能是：

    /Applications/JetBrains Toolbox/2022.3.4/JetBrains Toolbox.app/Contents/jbr/Contents/Home/lib/security/cacerts
    Linux

    cacerts 的檔案路徑 JetBrains IDE Linux 上安裝的是：

    /opt/jetbrains/jbr/lib/security/cacerts

  2. 判斷您需要匯入檔案的憑證cacerts。憑證檔案通常具有 .cer、 .crt或 .der 副檔名。如果您不確定需要新增哪些憑證，請聯絡您的網路管理員。

  3. 將憑證匯入cacerts金鑰存放區。您可以使用 Java keytool命令來執行此操作。

    1. 開啟命令提示字元並輸入下列命令：

      keytool -import -alias <alias> -file <certificate_file> -keystore <path_to_cacerts>

    2. 對於 <alias>，您可以為匯入的憑證新增名稱，以供稍後參考。此選項為選用。

    3. 針對 <certificate_file>，指定您要匯入之憑證的路徑。這應該是包含憑證的 .cer、 .crt或 .der 檔案的路徑。

    4. 對於 <path_to_cacerts>，指定您在步驟 1 中儲存的cacerts金鑰存放區檔案的路徑。這是您要匯入憑證的檔案。

    例如，如果您想要my_certificate.cer將名為 的憑證匯入 JRE中綁定的 cacerts金鑰存放區 IntelliJ IDEA 在 Windows 上，而且您想要將別名提供給myalias憑證，該命令可能是：

    keytool -import -alias myalias -file my_certificate.cer -keystore "C:\Program Files\JetBrains\IntelliJ IDEA 2022.3.2\jbr\bin\cacerts"

  4. 在匯入過程中，系統會提示您輸入金鑰存放區密碼。cacerts 金鑰存放區的預設密碼為 changeit。

  5. 執行 命令後，系統會要求您信任憑證。若要確認憑證受信任並完成匯入，請輸入 yes。

  6. 除了 之外，您也可能需要將憑證新增至 IDE本身JRE。如需詳細資訊，請參閱中的伺服器憑證 JetBrains 文件中)。

顯示較多顯示較少

在 中設定憑證 Visual Studio Code

若要設定 Visual Studio Code 若要信任代理伺服器使用的 SSL或 TLS 憑證，請確定您已為作業系統設定下列代理設定。

為 設定下列代理設定 Visual Studio Code 在 macOS 上。

將憑證新增至您的 macOS 金鑰鏈

如果您還沒有，則必須將代理伺服器使用的憑證新增至您的 macOS 金鑰鏈。如需將憑證新增至金鑰鏈的資訊，請參閱 Keychain Access 使用者指南中的使用 Mac 上的 Keychain Access 將憑證新增至金鑰鏈。

安裝 Mac CA VSCode延伸模組

Mac CA VSCode延伸允許 Amazon Q 存取您在 Mac 上新增至 Keychain Access 的憑證。

若要安裝擴充功能：

  1. 在 mac-ca-vscode中搜尋 VS Code 擴充功能窗格，然後選擇安裝 。

  2. 重新啟動 VS Code.

在 中更新代理設定 VS Code 在 macOS 上

更新下列設定以確保 VS Code 已為您的代理正確設定 。

  1. 在 中開啟設定 VS Code.

  2. 在搜尋列中，輸入 proxy。

  3. 在 Http： Proxy 欄位中，新增您的 Proxy URL。

  4. 取消選取 Http：Proxy Strict SSL。

  5. 在 Http： Proxy Support 下拉式清單中，選擇 。

  6. 在設定搜尋列中，輸入 http.experimental.systemCertificatesV2。選取 Http › 實驗：系統憑證 V2。

為 設定下列代理設定 Visual Studio Code 在 Windows 上。

在 Windows 上將憑證新增為受信任的根憑證

如果您還沒有，則必須將代理伺服器使用的憑證新增至 Windows 上的信任根憑證授權機構存放區。若要新增憑證，請完成下列程序：

  1. 開啟搜尋工具或執行命令視窗。

  2. 輸入以下內容以開啟 Certificate Manager 工具：

    certmgr.msc

  3. 選擇信任的根憑證授權機構存放區。

  4. 用滑鼠右鍵按一下憑證 ，選擇所有任務 ，然後選擇匯入...。

  5. 遵循提供的指示匯入代理憑證。

  6. 匯入憑證後，請確認已新增憑證。

    在信任的根憑證授權機構存放區中，按兩下憑證 。用滑鼠右鍵按一下您新增的憑證，然後選擇屬性 。在憑證用途 下，應選取啟用此憑證的所有用途選項。

安裝 Win-CA VSCode延伸模組

Win-CA VSCode擴充功能可讓 Amazon Q 存取您新增至 Windows 中信任根憑證的憑證。

若要安裝擴充功能：

  1. 在 win-ca 中搜尋 VS Code 設定窗格。

  2. 在注入下拉式清單中，選擇附加 。

在 中更新代理設定 VS Code 在 Windows 上

更新下列設定以確保 VS Code 已為您的代理正確設定 。

  1. 在 中開啟設定 VS Code.

  2. 在搜尋列中，輸入 proxy。

  3. 在 Http： Proxy 欄位中，新增您的 Proxy URL。

  4. 取消選取 Http：Proxy Strict SSL。

  5. 在 Http：代理支援下拉式清單中，選擇 上的 。

  6. 在設定搜尋列中，輸入 http.experimental.systemCertificatesV2。選取 Http › 實驗：系統憑證 V2。

  7. 重新啟動 VS Code.

允許存取 Amazon S3

在轉換期間，Amazon Q Developer Agent for code transformation 會將程式碼上傳至服務擁有的 Amazon S3 儲存貯體。如果您的網路或組織尚未設定對 Amazon S3 的存取，Amazon Q 將無法上傳您的專案。

為了確保 Amazon Q 可以上傳您的專案，請確定您的代理組態和其他網路元件，例如 Data Lost Prevention （DLP） 政策，已設定為允許存取 Amazon S3。您可能還需要允許列出 Amazon Q 上傳專案的 Amazon S3 儲存貯體。如需詳細資訊，請參閱Amazon Q 資源的資料周邊。

如果您轉換大型專案，DLP政策或其他網路元件可能會導致延遲，如果未將它們設定為允許列出 Amazon S3 儲存貯體，可能會導致上傳失敗。如果您選擇不允許列出儲存貯體，您可能需要轉換較小的專案，以便 Amazon Q 可以上傳它。

為什麼我的 Maven 命令失敗？

以下是 Maven 您在 中可能看到的組態問題 JetBrains 以及 Visual Studio Code IDEs。如果您解決問題，但仍看到 Maven 錯誤，您的專案可能有問題。使用錯誤日誌中的資訊來解決專案的任何問題，然後嘗試再次轉換專案。

更新 Maven 中的組態 JetBrains

如果 中的轉換失敗 JetBrains 由於 Maven 命令問題，錯誤日誌會顯示在執行索引標籤上。使用日誌中的資訊來解決問題。以下是您可能需要解決的一些問題：

  • 請確定您的 Maven 首頁路徑設定為搭售 。前往設定 ，然後展開建置、執行、部署區段。展開建置工具區段，然後展開 Maven。 在 Maven 首頁路徑下拉式清單中，選擇搭售 。

  • 請確定 Java 執行期環境 （JRE） 正在使用您的專案 JDK。前往設定 ，然後展開建置、執行、部署區段。展開 Maven 然後選擇 Runner 。在JRE下拉式清單中，選擇使用專案 JDK。

  • 請確定 Maven 已啟用。前往設定，然後選擇外掛程式 。搜尋 Maven 然後選擇 Maven 外掛程式內含的所有功能。如果您看到啟用按鈕，請選擇以啟用 Maven.

更新 Maven 中的組態 Visual Studio Code

如果 中的轉換失敗 VS Code 因為 Maven 命令問題，包含錯誤日誌的文字檔案會在新索引標籤中開啟。使用日誌中的資訊來解決問題。

請確定您已設定下列其中一個選項：

  • 您的專案包含 Maven 專案根資料夾中的包裝程式

  • 的版本 Maven Amazon Q 支援的 可在您的 上使用 PATH

如需詳細資訊，請參閱 如何將 Maven 新增至我的 PATH？

如何將 Maven 新增至我的 PATH？

若要在 中轉換程式碼 VS Code 不使用 Maven 包裝，您必須安裝 Maven 並將其新增至PATH變數。

檢查您是否擁有 Maven 已正確安裝，mvn -v請在 Visual Studio Code。 您應該會看到具有 的輸出 Maven 版本。

如果您在 Visual Studio Code 終端機，但不在您的作業系統終端機中，或者如果找不到 命令，您需要新增 Maven 至您的 PATH。

若要新增 Maven ，PATH請遵循機器的指示。

macOS

若要新增 Maven 至您的 macOS PATH，請完成下列步驟。

  1. 尋找您的 Maven 安裝目錄，或您安裝的資料夾 Maven，並儲存該資料夾的路徑。

  2. 在您選擇的編輯器中開啟 Shell 的組態檔案。對於最新的 macOS 版本，預設 Shell 為 ，zsh預設組態檔案位於 ~/.zshrc。

    將下列行新增至組態檔案底部。將 的值M2_HOME設定為您在步驟 1 中儲存的路徑：

    export M2_HOME="your Maven installation directory"
export PATH="${M2_HOME}/bin:${PATH}"

    這些命令會在所有終端機中提供 mvn命令。

  3. 關閉所有作業系統終端機視窗並結束所有 Visual Studio Code 執行個體。

  4. 驗證 Maven 已新增至您的 PATH，開啟新的作業系統終端機並執行下列命令：

    mvn -v

    您應該會看到具有 的輸出 Maven 版本。

  5. 看到您的 Maven 輸出，重新啟動 Visual Studio Code。 您可能還需要重新啟動您的機器。開啟新的 Visual Studio Code 終端機並執行下列命令：

    mvn -v

    輸出應與步驟 4 中的輸出相同。如果 Visual Studio Code 輸出不同，請嘗試以下操作，以確保您的設定正確：

    • 在 中檢查您的PATH變數 Visual Studio Code。 IDE 延伸模組可能會變更 ，PATH使其與您的區域PATH變數不同。解除安裝擴充功能，將其從 中移除PATH。

    • 在 中檢查預設 Shell Visual Studio Code。 如果將其設定為 以外的 zsh，請針對您的 Shell 重複這些步驟。

Windows

若要新增 Maven 至您的 Windows PATH，請完成下列步驟：

  1. 尋找您的 Maven 安裝目錄，或您安裝的資料夾 Maven，並儲存該資料夾的路徑。

  2. 開啟環境變數視窗：

    1. 選擇 Windows 按鈕以開啟搜尋列。

    2. 輸入Edit environment variables for your account並選擇它。

  3. 在環境變數視窗中，尋找路徑變數。如果您已有路徑變數，請選擇編輯... 進行更新。如果您沒有看到路徑變數，請選擇新增...來新增變數。

  4. 在出現的編輯環境變數視窗中，按兩下現有路徑進行編輯，或選擇新增以新增路徑項目。

    取代現有的 Maven 路徑項目，其中包含您在步驟 1 中儲存的路徑，或將路徑新增為新項目。在路徑結尾，新增 \bin為尾碼，如下列範例所示：

    C:\Users\yourusername\Downloads\apache-maven-3.9.6-bin\apache-maven-3.9.6\bin

  5. 選擇確定以儲存路徑項目，然後在環境變數視窗中再次選擇確定。

  6. 開啟新的命令提示字元並執行下列命令：

    mvn -v

    您應該會看到具有 的輸出 Maven 版本。

為什麼 Amazon Q 無法建置我的程式碼？

如果在 Amazon Q 建置程式碼時轉換失敗，您的專案可能無法針對 Amazon Q 建置程式碼的環境進行正確設定。您可能需要更新建置組態或程式碼實作。

檢閱 Amazon Q 提供的建置日誌輸出，以判斷您可以對專案進行的變更。以下是一些可能阻礙 Amazon Q 建置程式碼的常見問題。

移除 pom.xml 中的絕對路徑

如果您的 pom.xml 檔案中有絕對路徑，Amazon Q 將無法尋找相關檔案，因此可能無法建置程式碼。

以下是您在pom.xml檔案中可能擁有的絕對路徑範例：

<toolspath>
    <path>/Library/Java/JavaVirtualMachines/jdk-11.0.11.jdk/Contents/Home/lib/tools.jar</path>
</toolspath>

您可以不使用絕對路徑，而是使用指標建立相對路徑。以下是如何使用相對路徑取代先前絕對路徑的範例：

<toolspath>
    <path>${java.home}/../lib/tools.jar</path>
</toolspath>

在單位測試中移除本機或外部資料庫

Amazon Q 在建置程式碼時，會在專案中執行任何單位測試。如果單位測試呼叫本機或外部資料庫，Amazon Q 將無法存取資料庫，導致建置失敗。若要防止建置失敗，您必須從單位測試中移除資料庫呼叫，或在提交轉換之前移除單位測試。

為什麼我的轉換在 55 分鐘後失敗？

如果您的程式碼轉換任務在 55 分鐘後失敗，則程式碼建置時間可能會超過建置時間限制。建立程式碼的時間限制目前為 55 分鐘。

如果本機建置時間需要 55 分鐘或更長的時間，請縮短專案的建置時間來轉換程式碼。如果您的本機建置比使用程式碼轉換的建置更快，請檢查您的專案是否有可能失敗的任務，或在不同的環境中花費較長的時間。考慮停用長時間執行的測試案例。也請考慮使用逾時嘗試存取安全IDE環境或網際網路中可能無法使用的資源。

為什麼我無法下載轉換後的程式碼？

如果您在轉換完成後無法下載程式碼，則可能是下列其中一個問題所造成。請參閱與您在 Amazon Q 中看到的錯誤對應的主題。

縮小專案大小

轉換完成後，Amazon Q 會產生輸出成品，其中包含具有升級程式碼的 diff，以及包含其變更相關資訊的轉換摘要。輸出成品必須為 1 GB 或以下， IDE才能下載。

如果輸出成品超過限制，您將無法下載升級的程式碼或轉換摘要。嘗試轉換較小的專案，以防止較大的輸出成品。如果問題仍然存在，請聯絡 AWS Support。如需 AWS Support 與 Amazon Q 聯絡的相關資訊，請參閱 使用 Amazon Q 開發人員聊天 AWS Support。

24 小時內下載程式碼差異

具有升級程式碼的程式碼 diff 檔案僅在轉換完成後 24 小時內可用。如果轉換完成已超過 24 小時，請重新啟動轉換以下載 diff 檔案。

在 中設定代理設定 IDE

所以此 Amazon Q Developer Agent for code transformation 從服務擁有的 Amazon S3 儲存貯體下載升級的程式碼。下載程序的一部分涉及使用 SSL或 TLS憑證來建立 Amazon S3 和 之間的通訊IDE。如果您使用代理伺服器，代理伺服器使用的 SSL或 TLS 憑證必須受信任，否則 Amazon Q 無法上傳您的專案。

若要下載程式碼，您可能需要將 IDE 設定為信任憑證或更新其他代理設定。如需更新代理設定的詳細資訊，請參閱 在 中設定代理設定 IDE。

在 中移除萬用字元 JetBrains 代理設定

如果您已在 中設定代理設定 JetBrains IDE，您可能會在下載升級的程式碼時看到下列錯誤：

software.amazon.awssdk.core.exception.SdkClientException: 
Unable to execute HTTP request: Dangling meta character '*' near index 0

這可能是由於 代理IDE設定欄位中沒有代理中存在萬用字元 （*） 所致。SDK 使用的 Java Amazon Q Developer Agent for code transformation 不支援此欄位中的萬用字元項目。

若要下載程式碼，請從無代理欄位移除任何萬用字元，然後重新啟動您的 IDE。如果您需要指定應該繞過代理的主機，請使用規則運算式而非萬用字元。若要更新 中的代理設定 JetBrains IDE，請參閱中的HTTP代理 JetBrains 文件中)。

如何存取程式碼轉換日誌？

在 中存取日誌 JetBrains

如需有關如何存取 的資訊 JetBrains 日誌檔案，請參閱 中的尋找IDE日誌檔案 JetBrains 文件中)。

尋找 發出的日誌 Amazon Q Developer Agent for code transformation in JetBrains，搜尋下列字串的IDE日誌：

software.aws.toolkits.jetbrains.services.codemodernizer

程式碼轉換日誌以上述字串開頭。由 產生的日誌 Maven 會顯示在執行索引標籤上，並在日誌項目前後具有上述字串。

在 中存取日誌 Visual Studio Code

尋找 發出的日誌 Amazon Q Developer Agent for code transformation in VS Code，請完成下列步驟：

  1. 選擇頂端導覽列中的檢視，然後選擇 Command Palette 。

  2. 在顯示的命令調色盤Amazon Q: View Logs中搜尋。

  3. 日誌會在 中開啟IDE。若要搜尋 的日誌檔案CodeTransformation，請使用 CMD + F或 Control + F。

中的程式碼轉換日誌 VS Code 字首為 CodeTransformation:。以下是在 中產生的日誌範例 VS Code 對於 Maven 複製相依性錯誤：

2024-02-12 11:29:16 [ERROR]: CodeTransformation: Error in running Maven copy-dependencies command mvn = /bin/sh: mvn: command not found

如何找到轉換任務 ID？

在 中尋找您的任務 ID JetBrains

若要在 中尋找轉換任務 ID JetBrains，前往轉型中心中的轉型詳細資訊索引標籤，然後選擇顯示任務狀態 （時鐘） 圖示。

在 中尋找您的任務 ID Visual Studio Code

若要在 VS 程式碼中尋找轉換任務 ID，請前往轉換中樞，然後選擇顯示任務狀態 （時鐘） 圖示。