构建疑难解答 - 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

如果您收到“命令未找到：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

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

权限被拒绝

如果您收到“权限被拒绝”的错误，这意味着 Gradle 可能存在于正确的位置，但不可执行。您可以在 *nix 系统上使用 chmod +x path/to/executable 来解决此问题。

其他安装失败

如果 gradle —-version 可以工作，但您的所有构建都以相同的错误失败，则可能是您的 Gradle 构建配置脚本之一有问题。

您可以通过运行 gradle help 来验证 Gradle 脚本的问题，它会执行配置脚本但不执行任何 Gradle 任务。如果错误仍然存在，则意味着构建配置存在问题。如果不是，则问题存在于执行一个或多个请求的任务时（Gradle 先执行配置脚本，然后执行构建步骤）。

调试依赖解析

常见的依赖解析问题，例如解决版本冲突，已在依赖解析疑难解答中介绍。

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

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 Daemon 的额外日志可以在 $GRADLE_USER_HOME/daemon/8.14/ 下找到。

任务应该处于 UP-TO-DATE 状态时却执行了

--info 日志解释了任务为何执行，尽管构建扫描通过进入时间线视图并单击您要检查的任务，以可搜索的、可视化的方式完成此操作。

troubleshooting task execution build scan

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

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

调试 IDE 集成

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

刷新 IntelliJ IDEA

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

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

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

刷新 Eclipse（使用 Buildship）

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

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

Daemon 连接问题疑难解答

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

$ 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 地址。

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

您可以在 daemon 日志文件（$GRADLE_USER_HOME/daemon/<Gradle version>/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 中发现了 bug，请在 GitHub 上提交问题。

此页面有帮助吗？