# Gradle 任务

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

Gradle 任务是在 Gradle 构建周期中执行的一小段工作。 如需了解任务概念的详细信息，请参见 [Gradle 文档](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html#sec:projects_and_tasks)。

IntelliJ IDEA 允许您在项目中运行、调试和管理 [Gradle](gradle.html) 任务。

## 运行 Gradle 任务

您可以通过多种方式运行 Gradle 任务，例如从   运行任何内容  窗口、使用 [运行配置](run-debug-gradle.html)、从上下文菜单运行它们，甚至使用一个运行配置运行多个任务。

> **Tip:**
> 您还可以通过 [Run Anything](#run_anything_gradle)窗口运行 Gradle 命令行选项。

Procedure: 在 Run Anything 窗口中运行一个 Gradle 任务

1. 在   Gradle  工具窗口中，点击工具栏上的 ![执行 Gradle 任务](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle.icons.gradle.svg)。 或者，按两次 `Ctrl` (Windows), `Ctrl` (macOS), `Ctrl` (IntelliJ IDEA Classic (macOS)), `Ctrl` (macOS System Shortcuts), `Ctrl` (XWin), `Ctrl` (GNOME), `Ctrl` (KDE), `Ctrl` (Emacs), `Ctrl` (Sublime Text), `Ctrl` (Sublime Text (macOS)), `Ctrl` (Visual Studio), `Ctrl` (Visual Studio (macOS)), `Ctrl` (NetBeans), `Ctrl` (Eclipse), `Ctrl` (Eclipse (macOS)) 打开   运行任何内容   窗口。

2. 在   运行任何内容  窗口中，开始输入您要执行的任务名称。 要执行多个任务，请输入任务名称，并使用 Space 分隔每个新任务。 或者，向下滚动到   Gradle 任务   部分并选择您需要的任务。 按 `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS))。

![输入任务名称](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_task_entered.png)

如果您有 [linked projects](gradle.html#link_gradle_project)并且希望为指定的项目运行一个任务，那么在   运行任何内容  窗口的右上角，从   项目  列表中选择项目的名称，并在搜索栏中输入您的任务名称。

> **Note:**
> 如果您已为项目配置了选项（例如  `离线模式` ），IntelliJ IDEA 将自动将配置包括在运行范围内。

3. IntelliJ IDEA 运行指定任务并在   运行  工具窗口中显示结果。

![运行工具窗口：Gradle 任务](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_task_run_result.png) IntelliJ IDEA 还将任务保存在   运行任何内容   窗口的   最近   部分以及   运行配置   节点的   Gradle   工具窗口下。

![运行任何内容：最近](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_run_anything_recent.png)

Procedure: 通过运行配置运行 Gradle 任务

您可以向任务添加一些附加参数，将其配置为 [运行配置](run-debug-gradle.html)，保存后，在项目中需要时使用该运行配置。

1. 打开   Gradle   工具窗口。

2. 右键点击需要为其创建 Run configuration 的任务。

3. 从上下文菜单中选择   修改运行配置  。

![创建任务运行配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_run_config_create.png)

4. 在   创建运行配置：“任务名称”   中，您可以使用 [默认设置](run-debug-gradle.html#run_default) 或配置 [其他选项](run-debug-gradle.html#add_advanced) 并点击   OK  。

![Gradle 任务的运行配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/run_debug_gradle_task.png) IntelliJ IDEA 显示该任务在   运行配置   节点下。

![Gradle 工具窗口：运行配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_run_config_task_display.png)

5. 双击任务运行它或右键点击任务，然后从上下文菜单中选择   运行  。

![运行配置：上下文菜单](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_config_task_run.png)

Procedure: 从上下文菜单运行 Gradle 任务

1. 打开   Gradle   工具窗口。

2. 右键点击您要运行的任务。

3. 从上下文菜单中选择   运行 'task name'  。

![Gradle 工具窗口：上下文菜单](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_task_run_from_menu.png)

Procedure: 同时运行多个 Gradle 任务

您可以为若干任务创建一个 [运行配置](run-debug-configuration.html)。

1. 选择  `运行 | 编辑配置`  `Alt+Shift+F10` (Windows), `⌃ ⌥ R` (macOS), `⌥ ⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ R` (macOS System Shortcuts), `Alt+Shift+F10` (XWin), `Alt+Shift+F10` (GNOME), `Alt+Shift+F10` (KDE), `Alt+Shift+F10` (Emacs), `Alt+Shift+F10` (Sublime Text), `⌃ ⌥ R` (Sublime Text (macOS)), `Ctrl+Alt+Shift+R` (Visual Studio), `⌘ ⌥ ⇧ R` (Visual Studio (macOS)), `Alt+Shift+F10` (NetBeans), `Alt+Shift+F10` (Eclipse), `⌃ ⌥ R` (Eclipse (macOS))。

[运行/调试配置](run-debug-configurations-dialog.html)对话框打开。

2. 在   运行/调试配置   对话框中，点击 ![添加图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.add.svg) 并选择   Gradle   添加一个新的配置。

![添加新的 Gradle 运行/调试配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_run_debug_config_add.png)

3. 在   运行/调试配置  对话框的右侧，在   名称  字段中输入您的配置名称。 此外，您可以指定要在何处运行配置。 请使用   运行   下拉列表指定运行目标选项。

请使用   运行  部分来指定运行配置的设置。

例如，请检查以下设置：

* 任务与实参 - 指定任务和 [参数](https://docs.gradle.org/current/userguide/gradle_command_line.html)，您希望使用此配置执行。 您可以运行多个任务。 点击 ![选项图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.general.inlineVariables.svg) 字段内以打开 任务与实参 对话框以选择所需选项。 例如，指定 `清理` 和 `构建` ，并添加参数 `--debug` 。

* Gradle 项目 - 点击 ![选择已注册的 Gradle 项目之一](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.open.svg) 并选择已注册的 Gradle 项目。

* 如果您想添加 VM 选项 ，请点击 修改选项 链接，在打开的对话框中，在 Java 部分，选择 添加 VM 选项 。 VM 选项 字段会添加到运行配置中，您可以指定所需的形参。 例如，指定 `-Xmx3g` 。

![Gradle 运行/调试配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/调试配置](run-debug-configuration.html)。

4. 点击   OK  。

创建的配置已添加到   运行配置  节点中的   Gradle 项目  工具窗口。

5. 双击配置以运行任务，或右键点击配置并选择   运行  。

![Gradle 工具窗口：运行配置](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_run_configuration.png)

## 调试 Gradle 任务和脚本

您可以像 [调试](debugging-code.html) 常规应用程序一样调试 Gradle 任务和脚本。

IntelliJ IDEA 为 Gradle 脚本和常规测试的每个调试会话打开一个选项卡。   调试  工具窗口包含   帧  和   变量  ，以及   控制台  输出。

![调试工具窗口](https://resources.jetbrains.com.cn/help/img/idea/2026.3/debugger_gradle.png)

您可以执行单步操作，并在调试会话中的单个选项卡下停止在  `build.gradle.kts` 和常规测试类中设置的断点处。

![逐步执行断点](https://resources.jetbrains.com.cn/help/img/idea/2026.3/stepping_gradle.animated.gif)

Procedure: 配置 Gradle 调试过程

1. 创建一个 [run/debug configuration](run-debug-configuration.html)。 如果您有现有的运行/调试配置，请从主菜单中选择它，然后点击   编辑配置  。

2. 在   运行/调试配置  页面上，点击   Gradle 调试  标签。

3. 请使用以下选项配置 Gradle 调试过程：

* 调试 Gradle 脚本 : 当您使用编辑器中的左侧栏或上下文菜单执行测试时，此选项被禁用。 这样做是为了加快调试过程。

* 在单独的调试选项卡中调试复刻的 Gradle 任务 ：当选择此选项时，任何新的调试过程都会在 调试 工具窗口中的不同选项卡下运行。 默认情况下，此选项是禁用的，调试过程在同一标签下执行。

* 调试执行图中的所有任务 ：当您选择此选项时，执行图中的每个任务都会被调试。 例如，您正在调试的任务的所有依赖任务也将被调试。

Procedure: 调试 Gradle 脚本任务

1. 在编辑器中打开您的  `build.gradle.kts` 。

2. 在边距处设置断点，然后右键点击运行 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.actions.execute.svg)图标。 在上下文菜单中选择   调试 <name>  。

![调试构建脚本](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_debug_build_script.png)

> **Note:**
> 如果您首先启动了常规测试的调试会话，然后打开现有的 [run/debug configuration](#control_debug)，选择   启用 Gradle 脚本调试   选项，保存更改并重新启动调试过程。

3. IntelliJ IDEA 启动调试会话，您可以在   调试  工具窗口中查看结果。

![调试工具窗口](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_debug_tool_win.png)

Procedure: 调试 Gradle 任务

使用   Gradle  工具窗口来调试实现  `org.gradle.process.JavaForkOptions` 接口的 Gradle 任务，例如 [test](http://gradle.org/docs/current/dsl/org.gradle.api.tasks.testing.Test.html)或 [run](http://gradle.org/docs/current/dsl/org.gradle.api.tasks.JavaExec.html)。

1. 在   Gradle  工具窗口中，点击项目，打开   任务  节点，然后右键点击您想调试的任务。

2. 在上下文菜单中，选择   调试  。

调试过程已启动且任务已添加到位于   运行配置  节点下的最近任务列表中。

## 为 Gradle 任务分配一个快捷键

IntelliJ IDEA 允许您为 Gradle 任务分配快捷键，并通过一个键执行这些任务。 您还可以为 Gradle 运行/调试配置分配快捷方式，该配置可以包含多个任务。

Procedure:

1. 在   Gradle  工具窗口中，右键点击所需任务。

2. 从上下文菜单中选择  `分配快捷键` 。

![Gradle 工具窗口：分配快捷键](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_assign_shorcut.png) [按键映射](settings-keymap.html) 对话框打开。

3. 在   按键映射  对话框中，在   Gradle  节点下导航到您的任务。

4. 右键点击任务，从打开的列表中选择您要分配的快捷方式类型。

![添加快捷方式](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_add_shorcut_options.png)

5. 在打开的对话框中，根据快捷键类型配置快捷键，然后点击   OK  。

在我们的案例中，让我们添加一个键盘快捷键。

![键盘快捷键对话框](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_keyboard_shortcut.png)

您可以看到快捷键显示在   Gradle   工具窗口中的任务旁边。

![Gradle 工具窗口：显示的快捷键](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_shortcut_displayed.png)

在   按键映射  对话框中，您可以添加一个您想要分配快捷方式的新任务。

Procedure:

1. 在   按键映射   对话框中，在   Gradle   节点下，点击   选择要分配快捷键的任务  。

![键位映射对话框：选择一个任务来分配快捷键](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_choose_task_while_in_keymap_dialog.png)

2. 在打开的对话框中，选择您需要的任务，然后点击   OK  。

![选择 Gradle 任务对话框](https://resources.jetbrains.com.cn/help/img/idea/2026.3/gradle_select_task_keymap.png) 任务已添加到   Gradle   节点下的列表中。 现在可以 [配置快捷键](#configure_shortcut)。

> **Tip:**
> 您可以创建一个 [quick list](customize-actions-menus-and-toolbars.html#configure_quick_lists) 来收藏常用的 Gradle 任务，并通过关联的快捷键引用该列表。

## 配置运行 Gradle 任务的触发器

IntelliJ IDEA 允许您在项目执行之前运行 Gradle 任务，或使用任务激活配置设置其他条件。

Procedure:

1. 在   Gradle   工具窗口中，右键点击 Gradle 项目。

2. 在上下文菜单中，选择   任务激活  。

3. 在   任务激活  对话框中，点击 ![添加图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.add.svg)。

4. 在   选择激活阶段  菜单上，选择何时运行您的任务，例如，  Before Build 、  After Sync 等。

5. 在   选择任务  菜单上，选择实际任务。

任务和激活阶段将被添加到   任务激活   对话框中的列表中。 您还可以在   Gradle   工具窗口中查看所选任务对应的激活阶段名称。

另外，您可以在   Gradle   工具窗口中右键点击要执行的任务，然后从上下文菜单中选择激活阶段名称。"

您还可以创建一个运行/调试配置，这将取决于一个 Gradle 任务。

Procedure:

1. 在主菜单中，转到  `运行 | 编辑配置`  以打开项目的运行/调试配置。

2. 在   运行/调试配置   对话框中，在   启动前   部分，点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.general.add.svg) 图标。

3. 在打开的列表中，选择   运行 Gradle 任务  。

4. 在   选择 Gradle 任务   对话框中，指定您要执行的项目和任务，然后启动该项目。 您可以指定一个 Gradle 关联项目或任何其他 Gradle 项目。 请注意，如果您的 Gradle 项目没有链接，那么 IntelliJ IDEA 将使用默认配置（例如，捆绑的 Gradle 版本）来运行该任务。

5. 点击   OK  。