Files
openidea/docs/zh/guide/build-tools.mdx
T
Gabriel Gondim b30657ec50 feat(java): Delegate IDE build/run actions to Maven (#2828)
jdtls builds launches with ECJ, which rejects some code javac accepts (for example a generic method call used as an if condition), so such a Maven project could not be run from the IDE. Settings › Build, Execution, Deployment › Maven › Delegate IDE build/run actions to Maven makes Automatic and Build (Make) launches of Maven modules compile with Maven, as Rebuild already did. Classes JDT wrote for sources with errors look up to date to Maven's incremental compiler, so a delegated launch JDT reports errors for recompiles everything and javac's result decides whether it starts. Editor diagnostics still come from jdtls. Off by default.

Co-authored-by: GGVidal <52431033+GGVidal@users.noreply.github.com>
2026-11-12 07:39:30 +08:00

132 lines
11 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: "构建工具"
description: "通过“构建”菜单构建项目,在 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**:
| 设置 | 作用 |
| ------------------------------------ | ------------------------------------------------------------------------------- |
| **将 IDE 构建/运行操作委托给 Maven** | 运行和调试时用 Maven(`javac`)构建 Maven 模块,而不是 jdtls |
| **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 的运行和测试配置会自动检测(参见[运行配置](/zh/guide/run))。
## 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 解释器的库)会显示在项目视图的 **外部库** 下,以只读方式打开。