疑難排解問題 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 無法上傳您的專案。

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

注意

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

設定憑證 JetBrains

若要設定您的 JetBrains IDEJava 執行階段環境 (JRE) 若要信任 Proxy 伺服器所使用的SSL或TLS憑證，您必須將SSL或TLS憑證匯入中的cacerts檔案JRE。該cacerts文件是一個文件，其中包含用於安全連接（例如HTTPS和）的受信任根證書SSL，它是安全設置JRE的一部分。若要匯入憑證，請完成下列程序。

注意

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

  1. 決定cacerts檔案的路徑JRE。內部cacertsJRE文件的路徑 JetBrains IDE取決於操作系統和版本 JetBrains IDE你正在使用.

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

    注意

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

    該jbr文件夾代表JRE捆綁 JetBrains IDEs，這是專為搭配使用而JRE量身打造的特定版本 JetBrains IDEs.

    Windows

    的cacerts文件路徑 JetBrains IDE安裝在視窗上是：

    <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 若要信任 Proxy 伺服器所使用的SSL或TLS憑證，請確定您已針對作業系統設定下列 Proxy 設定。

設定下列代理伺服器設定：Visual Studio Code 在 macOS 上。

將憑證新增至您的 macOS 鑰匙圈

如果您還沒有，則必須將代理服務器使用的證書添加到您的 macOS 鑰匙扣。如需將憑證加入鑰匙圈的相關資訊，請參閱《鑰匙圈存取使用手冊》中的「在 Mac 上使用鑰匙圈存取」將憑證加入鑰匙圈。

安裝 Mac CA VSCode 擴充功能

Mac CA VSCode 擴展允許 Amazon Q 訪問您添加到 Mac 上鑰匙串訪問的證書。

若要安裝擴充功能：

  1. mac-ca-vscode在「」中搜尋 VS Code 擴展程序窗格，然後選擇安裝。

  2. 重新啟動 VS Code.

更新代理伺服器設定 VS Code 在 macOS 上

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

  1. 開啟設定 VS Code.

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

  3. 在「HTTP: 代理」欄位中，新增您的代理伺服器URL。

  4. 取消選取「HTTP：代理嚴格」SSL。

  5. 在「Http: 代理 Support」下拉式清單中，選擇「開啟」。

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

設定下列代理伺服器設定 Visual Studio Code 在視窗上。

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

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

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

  2. 輸入下列命令以開啟 Certificate Manager 工具：

    certmgr.msc

  3. 選擇受信任的根憑證授權單位存放區。

  4. 以滑鼠右鍵按一下憑證，選擇所有工作，然後選擇匯入... 。

  5. 按照給出的說明導入您的代理證書。

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

    在「信任的根憑證授權單位」存放區中，按兩下「憑證」 在您新增的憑證上按一下滑鼠右鍵，然後選 在 [憑證目的] 下，應該選取 [啟用此憑證的所有用途] 選項。

安裝贏 CA 擴VSCode展

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

若要安裝擴充功能：

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

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

更新代理伺服器設定 VS Code 在視窗上

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

  1. 開啟設定 VS Code.

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

  3. 在「HTTP: 代理」欄位中，新增您的代理伺服器URL。

  4. 取消選取「HTTP：代理嚴格」SSL。

  5. 在「Http: 代理 Support」下拉式清單中，選擇「開啟」。

  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 可以上傳您的專案，請確定您的代理伺服器組態和其他網路元件 (例如資料遺失防護 (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然後選擇「流道」。在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 版本，默認外殼是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.

    • 檢查你的默認外殼 Visual Studio Code。 如果設定為以外的其他項目zsh，請針對您的 shell 重複這些步驟。

Windows

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

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

  2. 打開環境變量窗口：

    1. 選擇 Windows 按鈕打開搜索欄。

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

  3. 在「環境變數」視窗中，尋找「路徑」變數。如果您已經有路徑變數，請選擇 「編輯...」。 更新它。如果您沒有看到 Path 變數，請選擇 [新增...] 添加一個。

  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 會產生一個輸出成品，其中包含與已升級程式碼的差異，以及轉換摘要，其中包含所做變更的相關資訊。輸出成品必須小於 1 GB，才能下載它。IDE

如果輸出成品超過上限，您將無法下載升級的程式碼或轉換摘要。嘗試轉換較小的專案，以避免產生較大的輸出假影。如果問題仍然存在，請聯繫 AWS Support。 有關聯繫方式的信息 AWS Support 與 Amazon Q，請參閱使用 Amazon Q 開發人員聊天 AWS Support。

在 24 小時內下載代碼差異

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

在您的中配置代理設置 IDE

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

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

刪除通配符 JetBrains 代理設定

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

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

這可能是由於代理伺服器設定的 [無 Proxy 用於] 欄位中存在萬用字元 (*) 所造成。IDE所SDK使用的 Java Amazon Q Developer Agent for code transformation 不支援此欄位中的萬用字元項目。

若要下載您的程式碼，請從 [無 Proxy 用於] 欄位中移除任何萬用字元，然後重新啟動IDE. 如果您需要指定應略過 Proxy 的主機，請使用規則運算式而非萬用字元。若要更新您的中的代理HTTP伺服器設定 JetBrains IDE，請參閱 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. 選擇上方導覽列中的 [檢視]，然後選擇 [指令選項板]。

  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，移至 [轉換中樞] 中的 [轉換詳細資料] 索引標籤，然後選擇 [顯示 Job 狀態 (時鐘)] 圖示。

找到您的工作 ID Visual Studio Code

若要在 VS Code 中尋找轉換 Job ID，請移至 [轉換中樞]，然後選擇 [顯示工作狀態 (時鐘)] 圖示。