构建问题排查 - Gradle 构建系统

以下是一些常见问题和解决建议的集合。您可以获取其他提示，并在 Gradle 论坛和 StackOverflow #gradle 答案中搜索。

安装问题排查

如果您按照安装说明进行操作，但无法执行 Gradle 构建，以下是一些可能有帮助的提示。

如果您在调用 Gradle Wrapper 之外安装了 Gradle，则可以通过在终端中运行 gradle --version 来检查您的 Gradle 安装。

您应该看到类似这样的内容

❯ gradle --version

------------------------------------------------------------
Gradle {gradleVersion}
------------------------------------------------------------

Build time:            2024-06-17 18:10:00 UTC
Revision:              6028379bb5a8512d0b2c1be6403543b79825ef08

Kotlin:        1.9.23
Groovy:        3.0.21
Ant:           Apache Ant(TM) version 1.10.13 compiled on January 4 2023
Launcher JVM:  11.0.23 (Eclipse Adoptium 11.0.23+9)
Daemon JVM:    /Library/Java/JavaVirtualMachines/temurin-11.jdk/Contents/Home (no JDK specified, using current Java home)
OS:            Mac OS X 14.5 aarch64

如果不是，以下是您可能看到的其他情况。

命令未找到：gradle

如果您收到“command not found: gradle”，您必须确保 Gradle 已正确添加到您的 PATH 中。

JAVA_HOME 设置为无效目录

如果您收到类似以下的错误：

ERROR: JAVA_HOME is set to an invalid directory

将您环境中的 JAVA_HOME 变量设置为与您的 Java 安装位置匹配

$ export JAVA_HOME=/Users/user/Library/Java/JavaVirtualMachines/corretto-11.0.22/Contents/Home
$ echo $JAVA_HOME
/Users/user/Library/Java/JavaVirtualMachines/corretto-11.0.22/Contents/Home

您必须确保已正确安装 Java Development Kit 版本 8 或更高版本，正确安装了 JAVA_HOME 环境变量，并将 Java 添加到您的 PATH 中。

权限被拒绝

如果您收到“permission denied”，则意味着 Gradle 可能存在于正确的位置，但它不可执行。您可以使用 chmod +x path/to/executable 在基于 *nix 的系统上修复此问题。

其他安装失败

如果 gradle —-version 可以工作，但您的所有构建都失败并显示相同的错误，则可能是您的 Gradle 构建配置文件之一已损坏。

您可以通过运行 gradle help 来验证 Gradle 脚本的问题，这将执行配置文件，但不执行 Gradle 任务。如果错误仍然存在，则表示构建配置存在问题。否则，问题存在于执行一个或多个请求的任务时（Gradle 首先执行配置文件，然后执行构建步骤）。

调试依赖解析

常见的依赖解析问题，例如解决版本冲突，在排查依赖解析问题中进行了介绍。

您可以通过单击Dependencies视图并使用搜索功能，指定解析原因，来查看依赖树，并查看哪些已解析的依赖版本与请求的版本不同。

troubleshooting dependency management build scan

图 1. 使用构建扫描调试依赖冲突

带有过滤条件的实际构建扫描可供探索。

排查构建速度慢的问题

有关构建性能问题（包括“同步时间过长”），请参阅提升 Gradle 构建的性能。

Android 开发者应观看 Android SDK Tools 团队关于加速您的 Android Gradle 构建的演示。Android Studio 用户指南关于优化构建速度中也介绍了许多技巧。

调试构建逻辑

将调试器附加到您的构建

您可以通过将 org.gradle.debug 属性设置为“true”，然后将远程调试器附加到端口 5005，在 Gradle 构建本身中设置断点并调试 buildSrc 和独立插件。您可以通过将 org.gradle.debug.port 属性设置为所需的端口号来更改端口号。

要通过网络远程附加调试器，您必须将 org.gradle.debug.host 属性设置为机器的 IP 地址或 *（监听所有接口）。

❯ gradle help -Dorg.gradle.debug=true

使用 Kotlin DSL，您可以调试构建脚本本身。

以下视频演示了如何使用 IntelliJ IDEA 调试示例构建。

图 2. 构建脚本的交互式调试

添加和更改日志记录

除了控制日志记录详细程度之外，您还可以使用 --console=verbose 标志来控制生命周期日志记录中任务结果（例如“UP-TO-DATE”）的显示。

您还可以通过注册各种事件监听器来替换 Gradle 的大部分日志记录。一个自定义事件记录器的示例在日志记录文档中进行了解释。您还可以从外部工具控制日志记录，使它们更加详细以调试其执行。

来自 Gradle 守护进程的其他日志可以在 $GRADLE_USER_HOME/daemon/8.13/ 下找到。

任务本应为 UP-TO-DATE，但却被执行

--info 日志解释了任务为何被执行，但构建扫描通过转到Timeline视图并单击您要检查的任务，以可搜索、可视化的方式执行此操作。

troubleshooting task execution build scan

图 3. 使用构建扫描调试增量构建

您可以从此列表中了解任务结果的含义。

调试 IDE 集成

IDE 中的许多不常见的错误可以通过“刷新”Gradle 来解决。另请参阅有关在 IntelliJ IDEA 中和在 Eclipse 中使用 Gradle 的更多文档。

刷新 IntelliJ IDEA

这仅适用于链接到 IntelliJ 的 Gradle 项目。

从主菜单中，转到 View > Tool Windows > Gradle。然后单击Refresh图标。

图 4. 在 IntelliJ IDEA 中刷新 Gradle 项目

刷新 Eclipse（使用 Buildship）

如果您使用 Buildship for Eclipse IDE，您可以通过打开“Gradle Tasks”视图并单击“Refresh”图标，或通过在编辑 Gradle 脚本时从上下文菜单执行 Gradle > Refresh Gradle Project 命令来重新同步您的 Gradle 构建。

图 5. 在 Eclipse Buildship 中刷新 Gradle 项目

排查守护进程连接问题

如果您的 Gradle 构建在运行任何任务之前失败，您可能遇到网络配置问题。当 Gradle 无法与 Gradle 守护进程进程通信时，构建将立即失败，并显示类似于以下消息：

$ gradle help

Starting a Gradle Daemon, 1 stopped Daemon could not be reused, use --status for details

FAILURE: Build failed with an exception.

* What went wrong:
A new daemon was started but could not be connected to: pid=DaemonInfo{pid=55913, address=[7fb34c82-1907-4c32-afda-888c9b6e2279 port:42751, addresses:[/127.0.0.1]], state=Busy, ...

当使用网络地址转换 (NAT) 伪装时，可能会发生这种情况。启用 NAT 伪装后，应视为本地计算机的连接被屏蔽为来自外部 IP 地址。Gradle 拒绝连接到任何外部 IP 地址，这是一种安全预防措施。

此问题的解决方案是调整您的网络配置，使本地连接不会被修改为显示为来自外部地址。

您可以在守护进程日志文件（$GRADLE_USER_HOME/daemon/<Gradle 版本>/daemon-<PID>.out.log）中监视检测到的网络设置和连接请求。

2021-08-12T12:01:50.755+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding IP addresses for network interface enp0s3
2021-08-12T12:01:50.759+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Is this a loopback interface? false
2021-08-12T12:01:50.769+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding remote address /fe80:0:0:0:85ba:3f3e:1b88:c0e1%enp0s3
2021-08-12T12:01:50.770+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding remote address /10.0.2.15
2021-08-12T12:01:50.770+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding IP addresses for network interface lo
2021-08-12T12:01:50.771+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Is this a loopback interface? true
2021-08-12T12:01:50.771+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding loopback address /0:0:0:0:0:0:0:1%lo
2021-08-12T12:01:50.771+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding loopback address /127.0.0.1
2021-08-12T12:01:50.775+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.TcpIncomingConnector] Listening on [7fb34c82-1907-4c32-afda-888c9b6e2279 port:42751, addresses:[localhost/127.0.0.1]].
...
2021-08-12T12:01:50.797+0200 [INFO] [org.gradle.launcher.daemon.server.DaemonRegistryUpdater] Advertising the daemon address to the clients: [7fb34c82-1907-4c32-afda-888c9b6e2279 port:42751, addresses:[localhost/127.0.0.1]]
...
2021-08-12T12:01:50.923+0200 [ERROR] [org.gradle.internal.remote.internal.inet.TcpIncomingConnector] Cannot accept connection from remote address /10.0.2.15.

获取更多帮助

如果您在此处没有找到解决您问题的方案，请在帮助论坛上联系 Gradle 社区，或使用help.gradle.org搜索相关的开发者资源。

如果您认为您在 Gradle 中发现了错误，请在 GitHub 上提交问题。

此页对您有帮助吗？