本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Java 转换故障排查 以下信息可帮助您排查使用 Amazon Q 开发者版转换 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 IDEs，它是专为与使用而量身定制的 JRE 的特定版本。JetBrains IDEs ------ #### [ Windows ] 安装在 Windows 上的 JetBrains IDE `cacerts` 的文件路径为： ``` \jbr\bin\cacerts ``` 例如，如果您在 Windows 上将 JetBrains IDE 安装在默认位置，则路径可能是： ``` 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 ``` 例如，如果您在 macOS 上将 JetBrains IDE 安装在默认位置，则路径可能是： ``` /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 文档中的 [Server Certificates](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 钥匙串中。有关向钥匙串添加证书的信息，请参阅《钥匙串访问使用手册》中的[在 Mac 上使用“钥匙串访问”将证书添加到钥匙串](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`，然后选择 **Install**。 1. 重新启动 VS Code。 ##### 在 macOS 上更新 VS Code 中的代理设置 更新以下设置，确保您的代理已正确配置 VS Code。 1. 在 VS Code 中打开设置。 1. 在搜索栏中输入 `proxy`。 1. 在 **Http: Proxy** 字段中，添加您的代理 URL。 1. 取消选择 **Http: Proxy Strict SSL**。 1. 在 **Http: Proxy Support** 下拉列表中，选择 **on**。 1. 在设置搜索栏中，输入 `http.experimental.systemCertificatesV2`。选择 **Http › Experimental: System Certificates V2**。 ##### 在 Windows 上为 Visual Studio Code 配置证书 在 Windows 上为 Visual Studio Code 配置以下代理设置。 ##### 在 Windows 上将证书添加为受信任的根证书 如果还没有，则必须将代理服务器使用的证书添加到 Windows 上的受信任的根证书颁发机构存储中。要添加证书，请完成以下流程： 1. 打开搜索工具或 Run 命令窗口。 1. 输入以下命令以打开 Certificate Manager 工具： ``` certmgr.msc ``` 1. 选择 **Trusted Root Certification Authorities** 存储。 1. 右键单击 **Certificates**，选择 **All Tasks**，然后选择 **Import...**。 1. 按照给出的说明导入您的代理证书。 1. 导入证书后，确认证书已添加。 在 **Trusted Root Certification Authorities** 存储中，双击 **Certificates**。右键单击您添加的证书，然后选择 **Properties**。在 **Certificate purposes** 下，**Enable all purposes for this certificate** 选项应该是选中状态。 ##### 安装 Win-CA 扩展 VSCode 程序 [Win-CA VSCode 扩展](https://marketplace.visualstudio.com/items?itemName=ukoloff.win-ca)允许 Amazon Q 访问你在 Windows 中添加到可信根证书中的证书。 安装扩展程序： 1. 在 VS Code 设置窗格中搜索 `win-ca `。 1. 在 **Inject** 下拉列表中，选择 **append**。 ##### 在 Windows 上更新 VS Code 中的代理设置 更新以下设置，确保您的代理已正确配置 VS Code。 1. 在 VS Code 中打开设置。 1. 在搜索栏中输入 `proxy`。 1. 在 **Http: Proxy** 字段中，添加您的代理 URL。 1. 取消选择 **Http: Proxy Strict SSL**。 1. 在 **Http: Proxy Support** 下拉列表中，选择 **on**。 1. 在设置搜索栏中，输入 `http.experimental.systemCertificatesV2`。选择 **Http › Experimental: System Certificates V2**。 1. 重新启动 VS Code。 ### 允许访问 Amazon S3 在转换期间，Amazon Q 会将您的转码上传到服务拥有的 Amazon S3 存储桶。如果您的网络或组织尚未配置对 Amazon S3 的访问权限，则 Amazon Q 将无法上传您的项目。 为确保 Amazon Q 可以上传您的项目，请确保将代理配置和其他网络组件 [例如数据丢失防护（DLP）策略] 配置为允许访问 Amazon S3。您可能还需要将 Amazon Q 上传项目的 Amazon S3 存储桶列入允许列表。有关更多信息，请参阅[Amazon S3 存储桶 URLs 和 ARNs 允许名单](firewall.md#data-perimeters)。 如果您转换大型项目，DLP 策略或其他网络组件如果未配置为允许访问 Amazon S3 存储桶，则可能会导致延迟并妨碍成功上传。如果您选择不将存储桶列入允许列表，则可能需要转换一个较小的项目，以便 Amazon Q 可以将其上传。 ## 为什么我的 Maven 命令失败了？ 以下是你可能会在JetBrains和中看到的Maven配置问题Visual Studio Code IDEs。如果您解决了问题，但仍然看到 Maven 错误，则可能是您的项目出现了问题。使用错误日志中的信息来解决项目中的任何问题，然后尝试再次转换您的项目。 ### 在 JetBrains 中更新 Maven 配置 如果由于 Maven 命令问题导致 JetBrains 中转换失败，则错误日志将显示在 **Run** 选项卡上。使用日志中的信息解决问题。以下是您可能需要解决的一些问题： + 确保您的 Maven 主路径设置为 **Bundled**。在 **Settings** 对话框中，展开 **Build, Execution, Deployment** 部分。展开 **Build Tools** 部分，然后展开 **Maven**。在 **Maven home path** 下拉列表中，选择 **Bundled**。 + 确保 Java 运行时环境（JRE）正在使用您的项目 JDK。在 **Settings** 对话框中，展开 **Build, Execution, Deployment** 部分。展开 **Maven** 并选择 **Runner**。在 **JRE** 下拉列表中，选择 **Use Project JDK**。 + 确保 Maven 已启用。前往 **Settings**，然后选择 **Plugins**。搜索 Maven，然后选择 Maven 插件。如果您看到 **Enable** 按钮，请选择该按钮以启用 Maven。 ### 在 Visual Studio Code 中更新 Maven 配置 如果由于 Maven 命令问题导致 VS Code 中的转换失败，则会在新选项卡中打开包含错误日志的文本文件。使用日志中的信息解决问题。 确保您配置了以下任一选项： + 您的项目在项目根文件夹中包含一个 Maven 包装器 + 您的 `PATH` 中有 Amazon Q 支持的 Maven 版本 有关更多信息，请参阅[如何将 Maven 添加到我的 `PATH`？](#add-maven-to-path) ## 如何将 Maven 添加到我的 `PATH`？ 要在不使用 Maven 包装器的情况下在 VS Code 中转换代码，您必须安装 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. 打开“Environment Variables”窗口： 1. 选择 Windows 按钮以打开搜索栏。 1. 输入 `Edit environment variables for your account` 并选择它。 1. 在 **Environment Variables** 窗口中，查找 Path 变量。如果您已经有 Path 变量，请选择 **Edit...** 来更新它。如果看不到 Path 变量，请选择 **New...** 添加一个。 1. 在出现的 **Edit environment variable** 窗口中，双击现有路径进行编辑，或者选择 **New** 以添加新的路径条目。 将现有 Maven 路径条目替换为在步骤 1 中保存的路径，或者将该路径添加为新条目。在路径末尾添加 `\bin` 作为后缀，如下例所示： ``` C:\Users\yourusername\Downloads\apache-maven-3.9.6-bin\apache-maven-3.9.6\bin ``` 1. 选择 **OK** 保存路径条目，然后在 **Environment Variables** 窗口中再次选择 **OK**。 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 环境或 Internet 获得的资源的尝试使用超时设置。 ## 为什么我无法下载转换后的代码？ 如果您在转换完成后无法下载代码，可能是由以下某个问题所致。请参阅与您在 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 开发者与之聊天 支持](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 的代理设置的 **No proxy for** 字段中存在通配符（\$1）所致。Amazon Q 使用的 Java SDK 不支持此字段中的通配符条目。 要下载您的代码，请从 **No proxy for** 字段中删除所有通配符，然后重新启动 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)。 要查找 Amazon Q 在 JetBrains 中发出的日志，请在 IDE 日志中搜索以下字符串： ``` software.aws.toolkits.jetbrains.services.codemodernizer ``` 代码转换日志以前面的字符串开头。Maven 生成的日志显示在 **Run** 选项卡上，并且在日志条目前后都有前面的字符串。 ### Visual Studio Code 中的访问日志 要查找 Amazon Q 在 VS Code 中发出的日志，请完成以下步骤： 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** 的 Transformation details 选项卡，然后选择 **Show Job Status**（时钟）图标。 ### 在 Visual Studio Code 中查找您的任务 ID 要在 VS Code 中查找转换作业 ID，请转到 **Transformation Hub** 并选择 **Show Job Status**（时钟）图标。