本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Java 轉換問題故障診斷 以下資訊可協助您針對使用 Amazon Q Developer 轉換 Java 應用程式時常見的問題進行故障診斷。 **Topics** + [為什麼 Amazon Q 無法上傳我的專案？](#project-upload-fail) + [為什麼我的 Maven 命令會失敗？](#maven-commands-failing) + [如何將 Maven 新增至我的 `PATH`？](#add-maven-to-path) + [為什麼 Amazon Q 無法建置我的程式碼？](#build-fail) + [為什麼我的轉換在經過 55 分鐘後失敗？](#build-time-limit) + [為什麼我無法下載轉換後的程式碼？](#download-code-fail) + [如何存取程式碼轉換日誌？](#logs) + [如何找到我的轉換任務 ID？](#job-id) ## 為什麼 Amazon Q 無法上傳我的專案？ 如果您的專案上傳失敗，可能是因為下列其中一個問題。請參閱您在 Amazon Q 中所看到錯誤的對應主題。 **Topics** + [縮減專案大小](#reduce-project-size) + [在 IDE 中設定代理設定](#configure-proxy) + [允許存取 Amazon S3](#allowlist-s3-bucket) ### 縮減專案大小 為了轉換您的程式碼，Amazon Q 會產生專案成品，其中包含您的原始程式碼、專案相依性和組建日誌。轉換任務的專案成品大小上限為 2 GB。如果您收到與專案成品大小相關的錯誤，則必須縮減專案的大小，或嘗試轉換較小的專案。您可以在程式碼轉換日誌中檢視專案成品檔案的大小。如需詳細資訊，請參閱[如何存取程式碼轉換日誌？](#logs) ### 在 IDE 中設定代理設定 為了轉換程式碼，Amazon Q 會將專案成品上傳至服務擁有的 Amazon S3 儲存貯體。上傳過程涉及使用 SSL 或 TLS 憑證來建立 Amazon S3 與 IDE 之間的通訊。如果您使用代理伺服器，代理伺服器使用的 SSL 或 TLS 憑證必須受信任，否則 Amazon Q 無法上傳您的專案。 如果您收到與代理或憑證相關的錯誤，您可能需要設定讓 IDE 或作業系統信任您的憑證，或更新其他代理設定。 **注意** 如果您位於組織的代理伺服器或防火牆後方，也可能會遇到與憑證無關的問題。如果您完成下列設定憑證的程序後仍發生問題，請聯絡您的網路管理員，確認您可從 IDE 與 Amazon S3 進行通訊。如需詳細資訊，請參閱[允許存取 Amazon S3](#allowlist-s3-bucket)。 #### 在 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 產品所在的目錄。此目錄通常是在安裝過程中選擇。 `jbr` 資料夾代表 JRE 與 JetBrains IDE 綁定，這是專為搭配 JetBrains IDE 使用而打造的特定 JRE 版本。 ------ #### [ Windows ] Windows 上所安裝 JetBrains IDE 的 `cacerts` 檔案路徑為： ``` \jbr\bin\cacerts ``` 例如，如果您將 JetBrains IDE 安裝到 Windows 上的預設位置，則路徑可能是： ``` C:\Program Files\JetBrains\jbr\bin\cacerts ``` ------ #### [ macOS ] macOS 上所安裝 JetBrains IDE 的 `cacerts` 檔案路徑為： ``` /Applications/JetBrains Toolbox//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 ``` ------ 1. 確定您需要匯入 `cacerts` 檔案的憑證。憑證檔案的副檔名通常是 `.cer`、`.crt` 或 `.der`。如果您不確定要新增哪些憑證，請聯絡您的網路管理員。 1. 將憑證匯入 `cacerts` 金鑰存放區。您可以使用 Java `keytool` 命令進行這項操作。 1. 開啟命令提示字元並輸入下列命令： ``` keytool -import -alias -file -keystore ``` 1. 針對 ``，您可以為您要匯入的憑證新增名稱，以供後續參考。此選項為選用。 1. 針對 ``，指定您要匯入之憑證的路徑。此路徑應該是包含憑證的 `.cer`、`.crt` 或 `.der` 檔案的路徑。 1. 針對 ``，指定您在步驟 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" ``` 1. 在匯入程序期間，系統會提示您輸入金鑰存放區密碼。`cacerts` 金鑰存放區的預設密碼為 `changeit`。 1. 執行命令後，系統會要求您信任憑證。若要確認憑證受信任並完成匯入，請輸入 `yes`。 1. 除了 JRE 之外，您可能還需要將憑證新增至 IDE 本身。如需詳細資訊，請參閱 JetBrains 文件中的[伺服器憑證](https://www.jetbrains.com/help/idea/settings-tools-server-certificates.html)。 #### 在 Visual Studio Code 中設定憑證 若要設定 Visual Studio Code 信任代理伺服器所使用的 SSL 或 TLS 憑證，請確定您已為作業系統設定下列代理設定。 ##### 在 macOS 上設定 Visual Studio Code 中的憑證 在 macOS 上為 Visual Studio Code 設定下列代理設定。 ##### 將憑證新增至 macOS 鑰匙圈 您必須將代理伺服器使用的憑證新增至 macOS 鑰匙圈 (若您尚未這樣做)。如需有關將憑證新增至鑰匙圈的資訊，請參閱《Keychain Access 使用者指南》中的[使用 Mac 上的 Keychain Access 將憑證新增至鑰匙圈](https://support.apple.com/guide/keychain-access/add-certificates-to-a-keychain-kyca2431/mac)。 ##### 安裝 Mac CA VSCode 延伸模組 [Mac CA VSCode 延伸模組](https://marketplace.visualstudio.com/items?itemName=linhmtran168.mac-ca-vscode)可讓 Amazon Q 存取您新增至 Mac 上 Keychain Access 的憑證。 若要安裝延伸模組： 1. 在 VS Code 延伸模組窗格中搜尋 `mac-ca-vscode`，然後選擇**安裝**。 1. 重新啟動 VS Code。 ##### 在 macOS 上更新 VS Code 中的代理設定 更新下列設定，確保已為您的代理正確設定 VS Code。 1. 在 VS Code 中開啟設定。 1. 在搜尋列中，輸入 `proxy`。 1. 在 **Http：代理**欄位中，新增您的代理 URL。 1. 取消勾選 **Http：代理嚴格 SSL**。 1. 在 **Http：代理支援**下拉式清單中，選擇**開啟**。 1. 在「設定」搜尋列中，輸入 `http.experimental.systemCertificatesV2`。選取 **Http > 試驗：系統憑證 V2**。 ##### 在 Windows 上設定 Visual Studio Code 中的憑證 在 Windows 上為 Visual Studio Code 設定下列代理設定。 ##### 在 Windows 上新增憑證作為信任的根憑證 您必須將代理伺服器使用的憑證，新增至 Windows 上受信任的根憑證授權單位存放區 (若您尚未這樣做)。若要新增憑證，請完成下列程序： 1. 開啟搜尋工具或「執行」命令視窗。 1. 輸入下列命令以開啟 Certificate Manager 工具： ``` certmgr.msc ``` 1. 選擇**受信任的根憑證授權單位**存放區。 1. 用滑鼠右鍵按一下**憑證**，選擇**所有工作**，然後選擇**匯入...**。 1. 依照提供的指示匯入代理憑證。 1. 匯入憑證後，請確認憑證已新增。 在**受信任的根認證授權單位**存放區中，按兩下**憑證**。用滑鼠右鍵按一下您新增的憑證，然後選擇**屬性**。在**憑證用途**下，**啟用此憑證的所有用途**選項應為已選取狀態。 ##### 安裝 Win-CA VSCode 延伸模組 [Win-CA VSCode 延伸模組](https://marketplace.visualstudio.com/items?itemName=ukoloff.win-ca)可讓 Amazon Q 存取您新增至 Windows 中受信任的根憑證的憑證。 若要安裝延伸模組： 1. 在 VS Code 設定窗格中搜尋 `win-ca `。 1. 在**注入**下拉式清單中，選擇**附加**。 ##### 在 Windows 上更新 VS Code 中的代理設定 更新下列設定，確保已為您的代理正確設定 VS Code。 1. 在 VS Code 中開啟設定。 1. 在搜尋列中，輸入 `proxy`。 1. 在 **Http：代理**欄位中，新增您的代理 URL。 1. 取消勾選 **Http：代理嚴格 SSL**。 1. 在 **Http：代理支援**下拉式清單中，選擇**開啟**。 1. 在「設定」搜尋列中，輸入 `http.experimental.systemCertificatesV2`。選取 **Http > 試驗：系統憑證 V2**。 1. 重新啟動 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](firewall.md#data-perimeters)。 如果您轉換大型專案，而 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`？](#add-maven-to-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 所在的資料夾，並儲存該資料夾的路徑。 1. 在您選擇的編輯器中開啟 Shell 的組態檔案。近期 macOS 版本的預設 Shell 為 `zsh`，且預設組態檔案位於 `~/.zshrc`。 將以下行新增至組態檔案的底部。將 `M2_HOME` 的值設定為您在步驟 1 中儲存的路徑： ``` export M2_HOME="your Maven installation directory" export PATH="${M2_HOME}/bin:${PATH}" ``` 這些命令可在所有終端中提供 `mvn` 命令。 1. 關閉所有作業系統終端視窗，並結束所有 Visual Studio Code 執行個體。 1. 若要確認 Maven 已新增至您的 `PATH`，請開啟新的作業系統終端，並執行下列命令： ``` mvn -v ``` 您應該會看到包含您的 Maven 版本的輸出。 1. 看到您的 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 所在的資料夾，並儲存該資料夾的路徑。 1. 開啟「環境變數」視窗： 1. 選擇 Windows 按鈕以開啟搜尋列。 1. 輸入 `Edit environment variables for your account` 並選擇它。 1. 在**環境變數**視窗中，尋找 Path 變數。如果您已有 Path 變數，請選擇**編輯...** 進行更新。如果您未看到 Path 變數，請選擇**新增...** 新增該變數。 1. 在顯示的**編輯環境變數**視窗中，按兩下現有路徑以進行編輯，或選擇**新增**以新增路徑項目。 將現有的 Maven 路徑項目取代為您在步驟 1 中儲存的路徑，或新增路徑作為新項目。在路徑結尾處，新增 `\bin` 作為尾碼，如下列範例所示： ``` C:\Users\yourusername\Downloads\apache-maven-3.9.6-bin\apache-maven-3.9.6\bin ``` 1. 選擇**確定**以儲存路徑項目，然後在**環境變數**視窗中再次選擇**確定**。 1. 開啟新的命令提示字元，並執行以下命令： ``` mvn -v ``` 您應該會看到包含您的 Maven 版本的輸出。 ------ ## 為什麼 Amazon Q 無法建置我的程式碼？ 如果在 Amazon Q 建置程式碼時轉換失敗，則您的專案可能未針對 Amazon Q 建置程式碼的環境正確設定。您可能需要更新建置組態或程式碼實作。 檢閱 Amazon Q 提供的建置日誌輸出，以判斷是否有可對專案進行的變更。以下是一些可能導致 Amazon Q 無法建置程式碼的常見問題。 ### 移除 pom.xml 中的絕對路徑 如果您的 pom.xml 檔案中有絕對路徑，Amazon Q 將無法尋找相關檔案，因此可能無法建置您的程式碼。 以下是您的 `pom.xml` 檔案中可能包含的絕對路徑範例： ``` /Library/Java/JavaVirtualMachines/jdk-11.0.11.jdk/Contents/Home/lib/tools.jar ``` 您可以使用指標來建立相對路徑，而不使用絕對路徑。以下範例說明如何使用相對路徑取代先前的絕對路徑： ``` ${java.home}/../lib/tools.jar ``` ### 在單元測試中移除本機或外部資料庫 Amazon Q 建置程式碼時，會在您的專案中執行任何單元測試。如果單元測試呼叫本機或外部資料庫，Amazon Q 將無法存取資料庫，因而導致建置失敗。為了避免建置失敗，您必須從單元測試中移除資料庫呼叫，或是在提交轉換之前移除單元測試。 ## 為什麼我的轉換在經過 55 分鐘後失敗？ 如果您的程式碼轉換任務在經過 55 分鐘後失敗，可能是您的程式碼建置時間超過建置時間限制。目前建置程式碼的時間限制為 55 分鐘。 如果您的本機建置時間需要 55 分鐘或更長的時間，請縮短專案的建置時間來轉換程式碼。如果您的本機建置比使用程式碼轉換的建置更快，請檢查您的專案是否有可能失敗的任務，或是在不同環境中花費更長時間的任務。請考慮停用長時間執行的測試案例。另外，請考慮針對嘗試存取可能無法從安全的 IDE 環境或網際網路取得之資源的情況使用逾時。 ## 為什麼我無法下載轉換後的程式碼？ 如果您在轉換完成後無法下載程式碼，可能是因為下列其中一個問題。請參閱您在 Amazon Q 中所看到錯誤的對應主題。 **Topics** + [縮減專案大小](#reduce-project-size-output) + [在 30 天內下載程式碼差異](#download-30-hrs) + [在 IDE 中設定代理設定](#configure-proxy-download) + [移除 JetBrains 代理設定中的萬用字元](#remove-wildcard) ### 縮減專案大小 轉換完成後，Amazon Q 會產生輸出成品，其中包含升級後程式碼的差異，以及包含其所做變更相關資訊的轉換摘要。輸出成品必須為 1 GB 或更小，IDE 才能下載。 如果輸出成品超過限制，您將無法下載升級後的程式碼或轉換摘要。嘗試轉換較小的專案，以防止產生大型輸出成品。如果問題仍然存在，請聯絡 支援。如需 支援 與 Amazon Q 聯絡的相關資訊，請參閱 [使用 Amazon Q Developer 與 支援 聊天](support-chat.md)。 ### 在 30 天內下載程式碼差異 包含升級後程式碼的程式碼差異檔案只會在轉換完成後 30 天內提供。如果轉換完成後超過 30 天，請重新啟動轉換以下載差異檔案。 ### 在 IDE 中設定代理設定 Amazon Q 會從服務擁有的 Amazon S3 儲存貯體下載升級後的程式碼。下載過程涉及使用 SSL 或 TLS 憑證來建立 Amazon S3 與 IDE 之間的通訊。如果您使用代理伺服器，代理伺服器使用的 SSL 或 TLS 憑證必須受信任，否則 Amazon Q 無法上傳您的專案。 若要下載程式碼，您可能需要將 IDE 設定為信任憑證，或更新其他代理設定。如需有關更新代理設定的詳細資訊，請參閱 [在 IDE 中設定代理設定](#configure-proxy)。 ### 移除 JetBrains 代理設定中的萬用字元 如果您已在 JetBrains IDE 中設定代理設定，您可能會在下載升級後的程式碼時看到下列錯誤： ``` software.amazon.awssdk.core.exception.SdkClientException: Unable to execute HTTP request: Dangling meta character '*' near index 0 ``` 這可能是因為 IDE 代理設定的**無代理**欄位中有萬用字元 (\$1) 所造成。Amazon Q 使用的 Java SDK 不支援在此欄位中使用萬用字元項目。 若要下載程式碼，請移除**無代理**欄位中的任何萬用字元，然後重新啟動 IDE。如果您需要指定應略過代理的主機，請使用規則表達式，而非萬用字元。若要更新 JetBrains IDE 中的代理設定，請參閱 JetBrains 文件中的 [HTTP 代理](https://www.jetbrains.com/help/idea/settings-http-proxy.html)。 ## 如何存取程式碼轉換日誌？ ### 存取 JetBrains 中的日誌 如需如何存取 JetBrains 日誌檔案的相關資訊，請參閱 JetBrains 文件中的[尋找 IDE 日誌檔案](https://intellij-support.jetbrains.com/hc/en-us/articles/207241085-Locating-IDE-log-files)。 若要在 JetBrains 中尋找 Amazon Q 發出的日誌，請在 IDE 日誌中搜尋下列字串： ``` software.aws.toolkits.jetbrains.services.codemodernizer ``` 程式碼轉換日誌會以上述字串開頭。Maven 產生的日誌會顯示在**執行**索引標籤上，且日誌項目前後都會有上述字串。 ### 存取 Visual Studio Code 中的日誌 若要在 VS Code 中尋找 Amazon Q 發出的日誌，請完成下列步驟： 1. 在頂端導覽列中選擇**檢視**，然後選擇**命令面板**。 1. 在顯示的命令面板中搜尋 `Amazon Q: View Logs`。 1. 日誌會在 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**，然後選擇**顯示任務狀態** (時鐘) 圖示。