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

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

Java 轉換問題故障診斷

以下資訊可協助您針對使用 Amazon Q Developer 轉換 Java 應用程式時常見的問題進行故障診斷。

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

如果您的專案上傳失敗，可能是因為下列其中一個問題。請參閱您在 Amazon Q 中所看到錯誤的對應主題。

縮減專案大小

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

在 IDE 中設定代理設定

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

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

注意

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

在 JetBrains 中設定憑證

若要設定您的 JetBrains IDE Java 執行階段環境 (JRE) 使其信任代理伺服器使用的 SSL 或 TLS 憑證，您必須將 SSL 或 TLS 憑證匯入 JRE 中的 cacerts 檔案。cacerts 檔案中包含 HTTPS 和 SSL 等安全連線的受信任根憑證，同時也是 JRE 安全設定的一部分。若要匯入憑證，請完成下列程序。

注意

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

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

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

    注意

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

    jbr 資料夾代表 JRE 與 JetBrains IDE 綁定，這是專為搭配 JetBrains IDE 使用而打造的特定 JRE 版本。

    Windows

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

    <JetBrains Installation Folder>\jbr\bin\cacerts

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

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

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

    /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

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

    /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 的憑證匯入 Windows 上 IntelliJ IDEA 中所綁定 JRE 的 cacerts 金鑰存放區，並且要為憑證提供別名 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. 除了 JRE 之外，您可能還需要將憑證新增至 IDE 本身。如需詳細資訊，請參閱 JetBrains 文件中的伺服器憑證。

顯示較多顯示較少

在 Visual Studio Code 中設定憑證

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

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

將憑證新增至 macOS 鑰匙圈

您必須將代理伺服器使用的憑證新增至 macOS 鑰匙圈 (若您尚未這樣做)。如需有關將憑證新增至鑰匙圈的資訊，請參閱《Keychain Access 使用者指南》中的使用 Mac 上的 Keychain Access 將憑證新增至鑰匙圈。

安裝 Mac CA VSCode 延伸模組

Mac CA VSCode 延伸模組可讓 Amazon Q 存取您新增至 Mac 上 Keychain Access 的憑證。

若要安裝延伸模組：

  1. 在 VS Code 延伸模組窗格中搜尋 mac-ca-vscode，然後選擇安裝。

  2. 重新啟動 VS Code。

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

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

  1. 在 VS Code 中開啟設定。

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

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

  4. 取消勾選 Http：代理嚴格 SSL。

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

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

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

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

您必須將代理伺服器使用的憑證，新增至 Windows 上受信任的根憑證授權單位存放區 (若您尚未這樣做)。若要新增憑證，請完成下列程序：

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

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

    certmgr.msc

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

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

  5. 依照提供的指示匯入代理憑證。

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

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

安裝 Win-CA VSCode 延伸模組

Win-CA VSCode 延伸模組可讓 Amazon Q 存取您新增至 Windows 中受信任的根憑證的憑證。

若要安裝延伸模組：

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

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

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

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

  1. 在 VS Code 中開啟設定。

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

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

  4. 取消勾選 Http：代理嚴格 SSL。

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

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

  7. 重新啟動 VS Code。

允許存取 Amazon S3

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

為了確保 Amazon Q 能夠上傳您的專案，請確定您的代理組態和其他網路元件 (例如 Data Lost Prevention (DLP) 政策) 皆已設定為允許存取 Amazon S3。您可能還需要將 Amazon Q 上傳專案所在的 Amazon S3 儲存貯體加入允許清單。如需詳細資訊，請參閱要列入允許清單的 Amazon S3 儲存貯體 URL 和 ARN。

如果您轉換大型專案，而 DLP 政策或其他網路元件未設定將 Amazon S3 儲存貯體加入允許清單，則這些政策和元件可能導致延遲並造成無法成功上傳。如果您選擇不將儲存貯體加入允許清單，則可能需要轉換較小的專案，Amazon Q 才能將其上傳。

為什麼我的 Maven 命令會失敗？

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

在 JetBrains 中更新 Maven 組態

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

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

  • 確定 Java 執行階段環境 (JRE) 使用您的專案 JDK。前往設定，然後展開建置、執行、部署區段。展開 Maven 並選擇執行器。在 JRE 下拉式清單中，選擇使用專案 JDK。

  • 確定已啟用 Maven。前往設定並選擇外掛程式。搜尋 Maven，並選擇 Maven 外掛程式。如果您看到啟用按鈕，請選擇該按鈕以啟用 Maven。

在 Visual Studio Code 中更新 Maven 組態

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

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

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

  • 您的 PATH 上有 Amazon Q 支援的 Maven 版本

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

如何將 Maven 新增至我的 PATH？

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

若要檢查是否已正確安裝 Maven，請在 Visual Studio Code 之外新的作業系統終端中執行 mvn -v。您應該會看到包含您的 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 輸出不同，請嘗試下列操作，以確定您的設定正確無誤：

    • 在 Visual Studio Code 中檢查您的 PATH 變數。IDE 延伸模組可能會更改 PATH，因而使其與您的本機 PATH 變數不同。解除安裝延伸模組，以將其從 PATH 中移除。

    • 檢查 Visual Studio Code 中的預設 Shell。如果設定為 zsh 以外的值，請針對您的 Shell 重複上述步驟。

Windows

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

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

  2. 開啟「環境變數」視窗：

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

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

  3. 在環境變數視窗中，尋找 Path 變數。如果您已有 Path 變數，請選擇編輯... 進行更新。如果您未看到 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 才能下載。

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

在 30 天內下載程式碼差異

包含升級後程式碼的程式碼差異檔案只會在轉換完成後 30 天內提供。如果轉換完成後超過 30 天，請重新啟動轉換以下載差異檔案。

在 IDE 中設定代理設定

Amazon Q 會從服務擁有的 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 代理設定的無代理欄位中有萬用字元 (*) 所造成。Amazon Q 使用的 Java SDK 不支援在此欄位中使用萬用字元項目。

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

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

存取 JetBrains 中的日誌

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

若要在 JetBrains 中尋找 Amazon Q 發出的日誌，請在 IDE 日誌中搜尋下列字串：

software.aws.toolkits.jetbrains.services.codemodernizer

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

存取 Visual Studio Code 中的日誌

若要在 VS Code 中尋找 Amazon Q 發出的日誌，請完成下列步驟：

  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？

在 JetBrains 中尋找您的任務 ID

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

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

若要在 VS Code 中尋找轉換任務 ID，請前往 Transformation Hub，然後選擇顯示任務狀態 (時鐘) 圖示。