> ## Documentation Index
> Fetch the complete documentation index at: https://openidea.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 构建工具

> 通过“构建”菜单构建项目，在 Maven、Gradle 工具窗口中工作，以及管理 .NET、CMake、Cargo、Go 和 npm 项目。

OpenIDEA 没有自己的构建系统：它读取项目的构建文件，调用你本来就在用的构建工具，再把结果展示在 IDE 里。

## “构建”菜单

**构建** 菜单适用于所有支持的构建系统。OpenIDEA 会根据项目（或当前文件所在模块）自动选择构建系统。

| 操作 | macOS | Windows / Linux |
| - | - | - |
| **构建项目**：编译源码和测试 | `⌘F9` | `Ctrl+F9` |
| **构建模块**：编译当前文件所在模块 | `⌘⇧F9` | `Ctrl+Shift+F9` |
| **重新构建项目**：先清理再构建 | — | — |
| **构建工件**：打包产物 | — | — |

各操作实际执行的命令：

| 构建系统 | 识别依据 | 构建 | 重新构建 | 构建工件 |
| - | - | - | - | - |
| Maven | `pom.xml` | `mvn test-compile`（模块：`-pl <module> -am`） | `clean test-compile` | `package -DskipTests` |
| Gradle | `build.gradle(.kts)`、`settings.gradle(.kts)` | `classes testClasses` | `clean classes testClasses` | `assemble` |
| Cargo | `Cargo.toml` | `cargo build --all-targets` | 先 `cargo clean` 再构建 | `cargo build --release` |
| Go | `go.mod`、`go.work` | `go build ./...`（`go.work` 中的每个模块） | `go build -a ./...` | — |
| TypeScript | `tsconfig.json`、`package.json` | `tsc --noEmit`（优先用项目里安装的 `tsc`） | — | 用项目的包管理器运行 `build` 脚本 |
| CMake | `CMakeLists.txt` | 需要时先配置，再 `cmake --build` | `--clean-first` | — |

Maven 和 Gradle 使用设置里配置的 wrapper 或本地安装（见下文）。没有 `tsconfig.json` 但有 `build` 脚本的 TypeScript 项目会直接运行该脚本。

输出会实时显示在底部的 **构建** 工具窗口。编译错误和警告按文件分组，同时出现在“问题”视图中，并在编辑器里标出。**停止构建** 可以取消正在进行的构建。

## Maven

项目中有 `pom.xml` 时，右侧会出现 **Maven** 工具窗口。首次打开项目时，OpenIDEA 会在后台用 Maven 导入项目（读取有效 POM 和依赖树）。

树中依次是 **配置文件**，然后是每个项目及其 **生命周期**、**插件**（展开可看到各个目标）、**依赖**、**运行配置** 和子模块。双击目标即可运行，也可以多选后一起运行。右键目标可以选 **运行 '…'**、**调试 '…'** 和 **创建运行配置…**。从树中运行目标会生成一个临时运行配置。

工具栏：

* **重新加载所有 Maven 项目**：重新读取 POM 和依赖树。
* **添加 Maven 项目**：添加导入时没有找到的 `pom.xml`。右键项目可以取消链接。
* **运行 Maven 构建**：运行选中的目标。
* **执行 Maven 目标…**：弹出带目标补全的输入框（按 Tab 补全，按 Enter 运行），还会列出最近执行过的命令。
* **切换离线模式**（`-o`）和 **切换“跳过测试”模式**（`-DskipTests`）：对之后所有 Maven 运行生效。
* **分析依赖…**：打开依赖分析器。
* **Maven 设置…**：打开 **设置 › 构建、执行、部署 › Maven**。

树中 Profiles 下的复选框同样会作用于所有 Maven 运行。

### 修改后重新加载

在编辑器里修改 POM 后，工具窗口会提示 **自上次重新加载以来构建文件已更改**，并提供 **加载 Maven 更改** 按钮。如果构建文件是在编辑器之外改动的（比如 `git pull` 或其他工具），Maven 项目会自动重新加载。

### `pom.xml` 中的编辑器支持

在 `${property}` 上 `⌘` 点击 / `Ctrl` 点击（或 **导航 › 声明或用法**，`⌘B` / `Ctrl+B`），会跳到定义它的属性，无论它在当前 POM 还是父 POM 中。在没有写版本号的依赖或插件上使用，会跳到提供版本的 `<dependencyManagement>` 或 `<pluginManagement>` 条目。

### Maven 设置

**设置 › 构建、执行、部署 › Maven**：

| 设置 | 作用 |
| - | - |
| **JRE** | Maven 同步、构建、目标和测试使用的 JDK |
| **Maven 主路径** | 使用指定的 Maven 安装，而不是项目里的 `mvnw` |
| **用户设置文件** | 作为 `-s` 传入 |
| **Toolchains 文件** | 作为 `-t` 传入 |
| **本地仓库** | 作为 `-Dmaven.repo.local` 传入 |
| **活动 profiles** | 逗号分隔的 profile（`-P`），`!id` 表示排除 |
| **线程数** | 作为 `-T` 传入（如 `4` 或 `2C`） |
| **使用 Maven Daemon (mvnd)** | 构建、同步和运行配置都通过 `mvnd` 执行；找不到 mvnd 或 JDK 低于 17 时退回 `mvn` |

## Gradle

项目中有 Gradle 构建文件时，右侧会出现 **Gradle** 工具窗口。首次打开项目时，OpenIDEA 会在后台用 Gradle 读取任务列表。

树中是根项目及其 **任务**（已分组）、**运行配置** 和子项目，双击任务即可运行。工具栏有 **重新加载所有 Gradle 项目**、**关联 Gradle 项目**（添加没被识别到的构建）、**运行 Gradle 任务**、**执行 Gradle 任务…**、**切换离线模式**（`--offline`）和 **分析依赖…**。

构建脚本变化后，工具窗口会提示 **自上次重新加载以来构建文件已更改**，并提供 **加载 Gradle 更改** 按钮。

在构建脚本里，对版本目录别名（如 `libs.spring.boot.starter`）使用 **导航 › 声明或用法**，会跳到 `gradle/libs.versions.toml` 中的对应条目，悬停时也会显示其声明。在版本目录文件中，`version.ref` 和 bundle 成员都能跳到对应条目。

### Gradle 设置

**设置 › 构建、执行、部署 › Gradle**：

| 设置 | 作用 |
| - | - |
| **构建和运行使用** | 选 **Gradle** 时以 `JavaExec` 任务运行主类；选 **OpenIDEA** 时用 Java 语言服务器的 classpath 启动 |
| **Gradle 使用的 JVM** | Gradle 同步、任务、运行配置和测试使用的 JDK |
| **分发** | **使用 Gradle 包装器**（没有时依次尝试 `mise` / `asdf` 固定的 Gradle、`PATH` 中的 Gradle），或 **本地安装** 并指定 **Gradle 主路径** |
| **Gradle 用户主目录** | 设置 `GRADLE_USER_HOME` |

## 依赖分析器

在 Maven 或 Gradle 工具窗口中，或在 `pom.xml` / 构建脚本的右键菜单中选择 **分析依赖…**，会在编辑器标签页中打开依赖分析器，内容包括：

* Maven 模块的依赖树（通过 `dependency:tree -Dverbose` 读取，被省略的重复项也会列出），或 Gradle 项目按配置解析出的依赖；
* 版本冲突（勾选 **仅显示冲突**），可以树形或列表显示；
* 引入某个库的所有路径，可以用 **跳转到源代码** 定位到声明处。

对 Maven 项目，**排除** 会在 POM 中添加 `<exclusion>` 并重新加载。

## .NET

**.NET** 工具窗口（右侧，可在“查找操作”中运行 **.NET 工作区** 打开）列出解决方案中的项目。选中项目后可以查看目标框架、项目引用、NuGet 包和测试：

* 搜索 NuGet，安装、更新、移除包；
* **发现 .NET 测试**，以及 **运行所有测试** / **运行测试**；
* **安装 TRX 报告支持**：为 Microsoft.Testing.Platform 项目安装报告扩展，测试结果才能显示在测试树里。

**重新加载 .NET 工作区** 会重新读取项目。.NET 的运行和测试配置会自动检测（参见[运行配置](https://openidea.sh/zh/guide/run.md)）。

## CMake

**设置 › 构建、执行、部署 › CMake** 中可以定义 CMake profile：构建类型、生成器、CMake 参数、构建目录、构建参数和环境变量。**构建项目** 使用第一个 profile；没有 profile 时，使用第一个已有 `CMakeCache.txt` 的目录，否则使用 `build`。CMake 目标会显示为运行配置。

## Cargo、Go、npm 等

这些构建系统没有专门的工具窗口：

* **Cargo**：每个二进制一个运行配置，另有 `cargo test`、`cargo build`，也可以用“构建”菜单。在 `Cargo.toml` 中，版本补全会列出已发布的 crate 版本；**有更新的依赖版本可用** 检查会提供快速修复，一键更新版本要求。
* **Go**：按模块生成运行和测试配置（包括 `go.work` 工作区），也可以用“构建”菜单。在 `go.mod` 中，版本补全会列出模块版本。
* **npm、pnpm、yarn、bun、Deno**：每个 `package.json` 脚本或 Deno task 一个运行配置，`package.json` 的 `scripts` 条目旁有 ▶ 图标。包管理器根据锁文件确定。
* **Make** 和 **just**：每个目标或 recipe 一个运行配置。
* **Composer**：`vendor/` 不存在或与 `composer.lock` 不一致时，会出现横幅提示，可以直接运行 `composer install`。

这些项目的依赖（crate、Go 模块、`node_modules` 中的包、Maven 和 Gradle 的 jar、JDK、Python 解释器的库）会显示在项目视图的 **外部库** 下，以只读方式打开。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.