# Gradle

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com.cn/help/idea/llms.txt).

> **TL;DR**
> 必需插件：   Gradle  、   Gradle for Java  （ [已安装](managing-plugins.html)并默认启用）
>
>
>
> Gradle 版本的支持：从 4.5.1 及更高版本开始。 请注意，对于低于 4.8 的 Gradle 版本和 Java 版本 11，存在一个未解决的 [Gradle 问题](https://github.com/gradle/gradle/issues/8431)。
>
>
>
> 如果在 IntelliJ IDEA 中工作，则无需单独安装 Gradle；IntelliJ IDEA 会代为完成。

IntelliJ IDEA 支持与 [Gradle](https://gradle.org) 的完整功能集成，可帮助自动化构建过程。 您可以轻松创建一个新的 Gradle 项目，打开并同步现有项目，同时处理多个 [链接项目](#link_gradle_project)，并对其进行管理。

您还可以创建一个 Gradle 项目并将其存储在 WSL 环境中，或从 WSL 文件系统中打开它。 如需更多信息，请参阅 [WSL](how-to-use-wsl-development-environment-in-product.html)部分。

Procedure: 创建新的 Gradle 项目

1. 启动 IntelliJ IDEA。

在 IntelliJ IDEA 主屏幕上，点击  `新建 | 项目` 。 如果已经打开了项目，请从主菜单中选择  `文件 | 新建项目` 。

2. 为新项目命名，并在必要时更改其位置。

3. 选择   创建 Git 仓库   将新项目置于版本控制之下。

您也可以随时在之后进行此操作。

> **Note:**
> `.gitignore`  文件无论如何都会生成。

4. 选择要在项目中使用的语言。 如果要添加通过插件提供的其他语言，请点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.add.svg)。

5. 在   构建系统  列表中选择   Gradle  。

6. 指定项目的 SDK (JDK)，或使用默认 SDK。

> **Tip:**
> 如果您的机器上没有 JDK，IntelliJ IDEA 可以很快为您 [下载 JDK](new-project-wizard.html)。
>
>
>
> Gradle 项目同步将等待 JDK 下载完成。

7. 所选的   添加示例代码  选项将创建一个包含基础代码示例的文件。

8. 选择   Gradle DSL  。 您可以选择   Kotlin   作为默认语法，或选择   Groovy   作为替代。

9. 在   高级设置   中，指定类似 [Maven coordinates](https://maven.apache.org/maven-conventions.html) 的字段。 这些设置可能会在您决定将项目部署到 Maven 仓库时有所帮助。 您指定的 [字段](https://maven.apache.org/pom.html#Maven_Coordinates)会被添加到  `build.gradle.kts` 文件中。

* Gradle 分发 ：选择 [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) 作为默认优选选项，或 本地安装 ，当您想使用特定的本地 Gradle 版本时。

* Gradle 版本 ：如果选择了 wrapper 选项，将使用最新的 Gradle 发行版，除非您取消选择 自动选择 选项并从下拉列表中选择特定版本。 或者，如果选择了 本地安装 ，那么将使用您在本地定义的版本。

* 自动选择 ：取消选择此选项以指定您想要在项目中使用的 Gradle 版本。

* 将这些设置用于未来的项目 ：选中此复选框，以在将来的项目中使用已配置的 Gradle 版本。

* GroupId - `groupId`  的新项目。 如果您计划在本地部署项目，您可以省略此字段。

* ArtifactId - `artifactId` ，这是您的新项目的名称。

* 版本 - `版本`  的新项目。 默认情况下，此字段会自动指定。

> **Tip:**
> 有关更多信息，请参阅 [Maven 命名约定](https://maven.apache.org/guides/mini/guide-naming-conventions.html)。

10. 点击   创建  。

> **Note:**
> 新创建的项目使用 JUnit 5。

Procedure: 使用 Gradle 作为构建工具创建 Jakarta EE 项目

1. 启动 IntelliJ IDEA。

在 IntelliJ IDEA 主屏幕上，点击  `新建 | 项目` 。 如果已经打开了项目，请从主菜单中选择  `文件 | 新建项目` 。

2. 在   生成器   部分下，选择   Jakarta EE  。

3. 配置您的项目，选择适当的选项，如项目名称、位置、语言，并选择   Gradle   作为您的构建工具。

4. 点击   创建  。

IntelliJ IDEA 创建一个带有专用   Gradle  工具窗口的 Gradle 项目，并添加必要的依赖项。

有关更详细的信息，请参阅 [教程：您的第一个 Jakarta EE 应用程序](creating-and-running-your-first-jakarta-ee-application.html)。

Procedure: 打开现有的 Gradle 项目

> **Note:**
> 如果您的 [offline mode](jetgradle-tool-window.html#offline)在项目中启用，项目的打开或重新导入可能会失败。 要解决此问题，请禁用离线模式并 [重新导入](work-with-gradle-projects.html#gradle_refresh_project)您的项目。

1. 如果 IntelliJ IDEA 当前未打开任何项目，请在 IntelliJ IDEA 主屏幕上点击   打开  。 否则，从主菜单中选择  `文件 | 打开` 。

如果您有一些需要从 IntelliJ IDEA 模型导入项目的自定义插件，请按 `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS)) 并搜索   从现有源创建项目   操作。

2. 在打开的对话框中，选择包含 Gradle 项目的目录，然后点击   OK  。

IntelliJ IDEA 在 IDE 中打开并同步项目。

如果您需要调整 Gradle 设置选项，请参阅 [Gradle 设置](gradle-settings.html)。

Procedure: 检查 Gradle JVM 和语言级别

* Gradle JVM ：当 IntelliJ IDEA 打开 Gradle 项目时，它会检查  `gradle.properties`  文件中  `org.gradle.java.home`  指定的适当 JVM 版本并将其用于该项目。 如果未指定，则使用项目 SDK。 或者，您可以使用 [Gradle 设置](gradle-settings.html) 配置 Gradle JVM。

* Language level ：语言级别设置应用于源根目录或模块。 如果一个 Gradle 项目有一个单一的 [linked project](#link_gradle_project)，那么项目默认语言级别设置为模块语言级别中的最低语言级别。 模块语言级别在  `build.gradle.kts`  文件的  `java`  块中被设置为  `sourceCompatibility` 。

预览部分设置为模块源集的预览标志的交集。 源设置模块语言级别设置为相应的  `sourceCompatibility`  属性和  `--enable-preview`  标志的组合。

Procedure: 将 Gradle 项目链接到 IntelliJ IDEA 项目

您可以在一个 IntelliJ IDEA 项目中包含多个 Gradle 项目。 如果您将部分代码保存在不同项目中，有一些需要处理的遗留项目、使用 [Gradle 组合构建](work-with-gradle-projects.html#gradle_composite_build) 或者与 [微服务](https://microservices.io) 一起工作，这可能会有所帮助。 您可以在 IntelliJ IDEA 中链接此类项目并同时管理它们。

当您 [打开](#gradle_import_project_start)一个 Gradle 项目时，该项目的链接会自动建立，并且   Gradle  工具窗口会启用。

如果 一个 IntelliJ IDEA 项目未链接到 Gradle 项目，则 Gradle 工具窗口将被禁用。 在这种情况下，IntelliJ IDEA 会显示一条消息，其中包含一个链接，可快速让您重新导入 Gradle 项目并启用   Gradle  工具窗口。 如果   Gradle   工具窗口处于活动状态，则表示您至少已链接一个 Gradle 项目。

1. 打开   Gradle   工具窗口。

2. 在   Gradle  工具窗口中，点击 ![“链接 Gradle 项目”图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.add.svg)以附加一个Gradle项目。

3. 在打开的对话框中，选择所需的  `build.gradle`  文件，并点击   OK  。

4. 在   从 Gradle 导入模块  窗口中，指定您尝试链接的 Gradle 项目的选项，然后点击   OK  。

项目已链接。   Gradle   工具窗口显示工具栏和 Gradle 实体的树状视图。

如果需要重新链接之前 [未链接的项目](work-with-gradle-projects.html#ignore_detach_gradle_project)，请在   项目   工具窗口中，右键点击已添加的  `build.gradle.kts` ，或如果它是 Gradle Groovy 模块，则右键点击  `build.gradle`  文件，然后选择   导入 Gradle 项目  。

Procedure: 为现有的 Gradle 项目添加一个新的 Gradle 模块

您可以向一个您已经在进行工作的项目中添加一个 Gradle module。

1. 在主菜单中，转到  `文件| 新建 | 模块` 以打开   新建模块  向导。

2. 如果现有项目不是 Gradle 项目，那么添加模块的过程与 [创建新的 Gradle 项目](#gradle_create_project)相同。 如果现有项目是一个 Gradle 项目，那么添加新模块的过程会更短。 您需要在   ArtifactId  字段中指定模块的名称。 其余信息会自动添加，您可以使用默认设置，也可以根据您的偏好设置进行更改。 另外，请注意，默认情况下，   作为模块添加到  字段显示您尝试添加模块的项目名称。 您可以点击 ![添加模块](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.nodes.Module.svg) 来选择其他名称，如果您有其他关联的 Gradle 项目。

Procedure: 将常规项目转换为 Gradle 项目

1. 在 IntelliJ IDEA 中打开您的项目。

2. 在   项目  工具窗口中，右键点击您的项目名称并选择  `新建 | 文件` 。

3. 在打开的对话框中输入  `build.gradle`  并点击   OK  。

4. 在编辑器中打开  `build.gradle`  文件，添加您需要的信息并重新打开您的项目。 项目的构建脚本文件中应包含以下基本信息：

```KOTLIN
plugins {
    java
}

group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

sourceSets {
    main {
        java {
            setSrcDirs(listOf("src"))
        }
    }
}

dependencies {
    testImplementation(platform("org.junit:junit-bom:5.10.0"))
    testImplementation("org.junit.jupiter:junit-jupiter")
}

tasks.test {
    useJUnitPlatform()
}


```

当您创建一个  `build.gradle.kts`  文件时，IntelliJ IDEA 会识别到 Gradle 构建脚本，并显示通知建议将项目作为 Gradle 加载。 在您加载项目后，IntelliJ IDEA 会启用 Gradle 工具窗口。

我们还建议您将  `settings.gradle.kts`  文件添加到您的项目中，并向其添加  `rootProject.name = "projectName"` 。 您的项目名称会是  `"projectName"` 。

Procedure: 访问 Gradle 设置

使用 [Gradle 设置](gradle-settings.html) 来配置每个链接的 Gradle 项目的构建和运行操作、Gradle 版本、项目更改的导入等等。

1. 在   设置   对话框（ `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))）中，转到  `构建、执行、部署| Gradle` 。

![Gradle 设置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_settings_preferences.png)

> **Tip:**
> 点击 ![Gradle 设置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.settings.svg) 工具栏，在   Gradle   工具窗口中访问 Gradle 设置。

2. 在 Gradle 设置页面上，配置可用选项并点击   OK  以保存更改。

Procedure: 为项目配置 Gradle 版本

IntelliJ IDEA 允许您使用不同选项来配置 Gradle 项目的 Gradle 版本。 您可以使用默认的 Gradle wrapper，作为任务使用 Gradle wrapper，或配置本地 Gradle distribution。

1. 请选择 ![Gradle 设置图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.settings.svg) 在   Gradle   工具窗口中，迅速访问   Gradle   设置页面。

![Gradle 设置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_settings_use_gradle_from.png)

2. 在   分发  列表中选择以下选项之一：

* 包装器 ：这是推荐的默认选项，使用 [Gradle 包装器](https://docs.gradle.org/current/userguide/gradle_wrapper.html)。 在这种情况下，将 Gradle 版本的更新委托给 Gradle，并在构建时自动下载 Gradle。 此选项还允许您使用精确的 Gradle 版本进行构建。 Gradle 版本保存在项目的 `gradle-wrapper.properties` 文件的 `gradle` 目录中，有助于消除任何 Gradle 版本问题。

* 包装器任务 ：选择此选项可根据 `wrapper` 任务配置来配置 Gradle 包装器。 如果想控制项目中使用的 Gradle 版本，这可能会很方便。 如果使用了默认的 Gradle 包装器选项，然后切换到 Gradle `wrapper` 任务配置，则在该任务中所做的更改会在项目导入期间自动更新。

* 本地安装 ：如果您想手动下载并使用特定版本的 Gradle，请选择此选项。 请指定 Gradle 安装位置以及 JVM 的位置，IntelliJ IDEA 将在导入指定的 Gradle 项目和执行其任务时运行 Gradle。

请点击   OK   以保存更改。

Procedure: 为 Gradle 项目添加 VM 选项

您可以使用  `gradle.properties`  文件为您的 Gradle 项目指定 VM options。

1. [创建](#gradle_create_project)或 [打开](#gradle_import_project_start)您的 Gradle 项目。

2. 在   项目  工具窗口中，右键点击项目，然后从上下文菜单中选择  `新建 | 文件` 。

3. 在   新建文件  对话框中，输入  `gradle.properties` 作为文件名，然后点击   OK  。

4. 在编辑器中打开已创建的文件，并添加所需的 VM 选项。

![gradle.properties 文件](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_vm_options.png)

有关更多信息，请参阅 [Gradle 文档](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties)。

Procedure: 增加 daemon 堆大小

您可以使用  `gradle.properties`  文件调整项目中现有的 Gradle daemon 堆大小。

1. [创建](#gradle_create_project)或 [打开](#gradle_import_project_start)您的 Gradle 项目。

2. 在   项目  工具窗口中，右键点击项目，然后从上下文菜单中选择  `新建 | 文件` 。

3. 在   新建文件  对话框中，输入  `gradle.properties` 作为文件名，然后点击   OK  。

4. 在编辑器中打开创建的文件，并使用  `org.gradle.jvmargs=(JVM 参数)` 属性指定所需的守护进程大小。

默认大小是  `-Xmx512m "-XX:MaxMetaspaceSize=256m"` 。

请检查以下代码段作为语法示例：

```
org.gradle.jvmargs=-Xmx4096m

```

有关更多信息，请参阅 [Gradle 文档](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties)。

## 配置 Gradle 守护进程工具链

从 Gradle 8.8 版本开始，IntelliJ IDEA 支持 Gradle Daemon 工具链，帮助加快构建速度并管理项目 JDK。 此外，从 IntelliJ IDEA 版本 2025.1 开始，默认提供此支持。

可以使用守护进程工具链创建新项目，也可以向现有项目添加此支持。

Procedure: 为新项目配置 Gradle 守护进程工具链

1. 打开 IDE，然后连续按两次 `Shift` (Windows), `Shift` (macOS), `Shift` (IntelliJ IDEA Classic (macOS)), `Shift` (macOS System Shortcuts), `Shift` (XWin), `Shift` (GNOME), `Shift` (KDE), `Shift` (Emacs), `Shift` (Sublime Text), `Shift` (Sublime Text (macOS)), `Shift` (Visual Studio), `Shift` (Visual Studio (macOS)), `Shift` (NetBeans), `Shift` (Eclipse), `Shift` (Eclipse (macOS)) 打开搜索窗口。

2. 输入   注册表   以打开   注册表   工具窗口，然后选择  `gradle.daemon.jvm.criteria.new.project`  选项。

3. [创建新的 Gradle 项目](#project_create_gradle)。

IntelliJ IDEA 会创建一个项目，其中包含  `gradle-daemon-jvm.properties`  文件，该文件位于  `gradle`  目录中，并包含项目 JDK 信息。

> **Note:**
> 对于 Gradle 版本 8.9 及更高版本，  `gradle-daemon-jvm.properties`  文件中指定的 JDK 信息会自动反映在 [Gradle 设置](gradle-settings.html#tool_chain) 中。

4. 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `构建、执行、部署 | 构建工具 | Gradle` 。

5. 在   Gradle   部分中，可以管理 JDK，并使用   Gradle JVM 标准   选择项目所需的 JDK。

![Gradle 项目设置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_projects_settings.png)

6. 在   版本   列表中，选择所需版本，也可以在   高级设置   部分中选择   供应商  。

7. 请点击   OK   以保存更改。

Procedure: 为现有项目配置 Gradle 守护进程工具链

1. 打开 Gradle 项目。

2. 在   项目  工具窗口中，右键点击  `gradle` 目录并选择  `新建 | 文件` 。

3. 在打开的窗口中，添加  `gradle-daemon-jvm.properties`  文件。

4. 在编辑器中打开  `gradle-daemon-jvm.properties` ，并添加 Gradle JVM 版本和供应商。

请查看以下示例：

```
toolchainVendor=ibm
toolchainVersion=19

```

5. 在编辑器中点击 ![“同步”图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle.icons.gradleLoadChanges.svg) (   同步 Gradle 更改  ) 以将更改同步到项目。

6. 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `构建、执行、部署 | 构建工具 | Gradle` 。

7. 在   Gradle   部分中，可以管理 JDK，并使用   Gradle JVM 标准   选择项目所需的 JDK。

![Gradle 项目设置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_projects_settings.png)

8. 在   版本   列表中，选择所需版本，也可以在   高级设置   部分中选择   供应商  。

9. 请点击   OK   以保存更改。

## See also

### 语言和框架特定指南

[Groovy](groovy.html)

### 过程

[Gradle 项目](work-with-gradle-projects.html)

### 外部链接

[Gradle](https://gradle.org/)