IntelliJ IDEA 中使用 Gradle

引言

Gradle 2008年发布，问世之初就受到多个开源社区的关注，2012年发布 1.0 版本时，已被 Hibernate、Spring 等多个项目采用，2013年 Google 选择 Gradle 作为 Android Studio 的官方构建工具，由此迎来爆发。随后 Gradle 持续演进，通过引入 Kotlin DSL 进一步提升体验，并致力于构建性能优化，如今已成为最受欢迎的构建工具之一。

从 IntelliJ IDEA 11 引入 Gradle 集成开始，到 IntelliJ IDEA 13 对 Gradle 提供 first-class support，再到 IntelliJ IDEA 14 支持 Gradle Test Runner、IntelliJ IDEA 2016.1 将 Project Model 与 Gradle 对齐、IntelliJ IDEA 2016.3 支持 Delegate IDE build/run actions to Gradle 以及 Gradle Composite Builds，至此 IntelliJ IDEA 基本完成了与 Gradle 的集成，并持续改进相关流程。

环境

IntelliJ IDEA 2025.3.2, Build #IU-253.30387.90, built on January 22, 2026

bundled plugin:

• Gradle (com.intellij.gradle)
• Gradle for Java (org.jetbrains.plugins.gradle)
• Gradle Declarative Support (com.android.tools.gradle.dcl)

兼容性

• Since 2023.2, IntelliJ Idea stops Java 7 supporting for Gradle JVM, https://youtrack.jetbrains.com/issue/IDEA-322594
• Since 2024.1, IntelliJ Idea stops supporting Gradle versions that older than 4.5, https://youtrack.jetbrains.com/issue/IDEA-342292
• Since 2026.1, IntelliJ Idea stops supporting Gradle versions that older than 4.6, https://youtrack.jetbrains.com/issue/IDEA-368384

IDEA Settings

IDEA Registry

<registryKey key="gradle.daemon.jvm.criteria" defaultValue="true" description="Enable the Gradle Daemon JVM criteria allowing to detect provisioning required toolchain for the build" />
<registryKey key="gradle.daemon.jvm.criteria.new.project" defaultValue="false" description="Enable to allow new projects to be created with the Gradle Daemon JVM criteria" />
<registryKey key="gradle.phased.sync.enabled" defaultValue="true" description="Enable the phased Gradle sync execution" />
<registryKey key="gradle.phased.sync.bridge.disabled" defaultValue="false" description="Disable bridges for the phased Gradle sync execution" />
<registryKey defaultValue="https://download.jetbrains.com/resources/intellij/plugins/gradle/v1/compatibility.json" description="URL to get updates for gradle/jvm compatibility matrix" key="gradle.compatibility.config.url" />
<registryKey defaultValue="86400" description="Time to check in seconds for gradle compatibility update. Set to 0 to disable updates" key="gradle.compatibility.update.interval" />
<registryKey key="gradle.settings.showDeprecatedSettings" defaultValue="false" description="Enables some deprecated setting in the Gradle settings dialog for troubleshooting" />
<registryKey key="gradle.tooling.use.external.process" defaultValue="false" description="Enable running gradle tooling api out of IDE process" />
<registryKey key="gradle.testLauncherAPI.enabled" defaultValue="true" description="Allow to use Test Launcher API to run tests when applicable" />
<registryKey key="gradle.tooling.adjust.user.dir" defaultValue="true" description="Change IDE user.dir system property during the Gradle tooling API call to have expected Gradle daemon CWD." />
<registryKey key="gradle.improved.hotswap.detection" defaultValue="false" description="Enable improved hotswap detection when build is delegated to Gradle" />
<registryKey key="gradle.exclude.build.files.when.in.source.set" defaultValue="false" description="If build.gradle[.kts] and settings.gradle[.kts] files should be excluded from content root, if they are in source set" />
<registryKey key="gradle.report.recently.saved.paths" defaultValue="true" description="Send information on recently saved files to Gradle Daemon right before executing a task" />
<registryKey key="gradle.version.catalogs.dynamic.support" defaultValue="true" description="Enable experimental support of version catalogs based on after-sync gradle models" />
<registryKey key="gradle.output.sync.progress.events" defaultValue="true" description="Send progress information like files download during project import to `Build Output`" />
<registryKey key="gradle.daemon.opentelemetry.agent.enabled" defaultValue="false" description="Enable performance trace collection in the Gradle daemon collected by OTLP java agent" />
<registryKey key="gradle.daemon.legacy.dependency.resolver" defaultValue="false" description="Use ArtifactResolutionQuery instead of ArtifactView to resolve Javadoc/Sources" />
<registryKey key="gradle.sync.use.eel.for.wsl" defaultValue="true" description="Use EEL API for WSL projects" />

Gradle Properties

AllProperties properties = new LayoutToPropertiesConverter(buildLayoutFactory).convert(initialProperties, buildLayoutResult);


    public AllProperties convert(InitialProperties initialProperties, BuildLayoutResult layout) {
        Map<String, String> properties = new HashMap<>();
        configureFromHomeDir(layout.getGradleInstallationHomeDir(), properties);         // <- $GRADLE_HOME/
        configureFromBuildDir(layout, properties);                                       // <- $BUILD_ROOT/
        configureFromHomeDir(layout.getGradleUserHomeDir(), properties);                 // <- $HOME/.gradle/
        configureFromSystemPropertiesOfThisJvm(Cast.uncheckedNonnullCast(properties));   // <- System.getProperties()
        properties.putAll(initialProperties.getRequestedSystemProperties());

        Map<String, String> daemonJvmProperties = new HashMap<>();
        configureFromDaemonJVMProperties(layout, daemonJvmProperties);                   // gradle/gradle-daemon-jvm.properties
        return new Result(properties, daemonJvmProperties, initialProperties);
    }

Sync All Gradle Projects - ExternalSystemUtil.refreshProjects

主要为，使用 Gradle Tooling API 解析项目，将结果转换成 IntelliJ Platform Project Model (DataNode<ProjectData>)，再更新到 IDE 内部各使用方。

BuildEnvironment

• DefaultBuildEnvironment (build identifier, gradle user home, gradle version, java home, jvm args)

GradleDslBaseScriptModel [>= Gradle 9.2] [bundled plugin >= 261.??]

• kotlinDslBaseScriptModel (scriptTemplatesClassPath, compileClassPath, implicitImports)
• groovyDslBaseScriptModel (compileClassPath, implicitImports)

GradleModelFetchAction

 

参考

• History of Gradle Delegation Process in IntelliJ IDEA - Jetbrains Blog - 2023

更多

调试 IntelliJ IDEA & bundled plugin Gradle

新建 IDE plugin 项目，设定目标 IDE 版本，设定运行环境 (intelliJPlatformTestingExtension.runIde)，关联源码 Jar。

注意：bundled plugin Gradle 依赖 gradle-api ("org.jetbrains.intellij.deps:gradle-api:x.y.0")，注意和 gradle-wrapper 区分，注意和 KotlinDslScriptModel 的 build.gradle.kts 和 settings.gradle.kts 环境区分。

build.gradle.kts

 val runIdeWithPlugins by intellijPlatformTesting.runIde.registering {
  // ...
  plugins {
    plugin("pluginId", "1.0.0")
    bundledPlugins("pluginId", "pluginId")
    disablePlugins("pluginId", "pluginId")
  }
}

调试 Gradle Daemon

在 gradle.properties 中添加 org.gradle.debug=true，这样 Daemon 运行时会自然添加 -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005.

• 也可在 IDE plugin 项目中，重写 configureSettings 方法，settings.withArgument("-Dorg.gradle.debug=true")

在 IDEA 中新建 Run/Debug Configurations，类型选 Remote JVM Debug，确认 Host 和 Port，执行即可。可在入口 GradleDaemon 打上断点。

或者按 Gradle Build scripts 方式调试。

调试 Gradle Build scripts

在 IDEA 的 Run/Debug Configurations 中添加 Run Options，开启 Debug Gradle scripts.