必须取消勾选“Delegate IDE build/run actions to Maven/Gradle”才能使IDEA调用本地Maven/Gradle；需手动指定解压安装路径、配置JVM与settings.xml，并重启项目以生效。
IntelliJ IDEA 默认使用内置的构建系统（如 Delegate IDE build/run actions to Maven/Gradle），但若想用本地安装的 Maven 或 Gradle 执行构建（比如调试构建脚本、复现 CI 环境、或绕过 IDE 缓存问题），就需要正确配置本地 Build 工具路径和行为。
确认已安装并验证本地 Maven/Gradle
IDEA 不会帮你装 Maven 或 Gradle，只负责调用。先确保命令行可用：
- Maven：终端执行 mvn -v，看到版本号且 M2_HOME（或 MAVEN_HOME）已设好
- Gradle：执行 gradle -v，推荐用 SDKMAN! 或手动解压安装，避免用 SDK 自带的 wrapper
路径建议选解压即用的目录（如 /opt/maven/apache-maven-3.9.6），别指向 /usr/bin/mvn 这类符号链接，IDEA 可能读不到真实 home。
在 IDEA 中指定本地 Maven/Gradle 路径
打开 Settings（Preferences on macOS）→ Build, Execution, Deployment → Build Tools，按需设置：
立即学习“Java免费学习笔记（深入）”；
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- Maven：在 Maven home path 选 “Maven installation directory”，点文件夹图标选你本地解压的根目录（如 /opt/maven/apache-maven-3.9.6）
- Gradle：在 Gradle JVM 选项目所需 JDK；Gradle user home 可自定义（如 ~/.gradle）；Gradle JVM 必须与构建脚本兼容（如 Gradle 8.x 需 JDK 17+）
改完点 OK，重启项目或刷新 Maven/Gradle 面板（右上角闪电图标），让 IDEA 重新解析依赖和生命周期。
关闭“委托给 IDE”的自动构建（关键步骤）
默认 IDEA 会拦截构建请求，用自己的逻辑跑（不走你配的 mvn/gradle 命令）。要真正用本地工具，必须关掉这个代理：
- 进入 Settings → Build, Execution, Deployment → Build Tools → Maven（或 Gradle）→ Runner
- 取消勾选 Delegate IDE build/run actions to Maven/Gradle
- （Gradle 项下）同时确认 Run tests using 设为 Gradle Test Runner，而非 IntelliJ IDEA
这样点击 “Build Project” 或运行 Maven goal（如 clean compile）时，IDEA 才会真正调用你配的本地 mvn/gradle 可执行文件，并显示完整控制台日志。
常见问题与建议
配置后仍不生效？试试这些：
- 检查终端里的 PATH 和 IDEA 启动方式：如果从桌面图标启动 IDEA，它可能没继承 shell 的环境变量（如 MAVEN_HOME），优先用 Settings 里手动指定路径
- Maven 的 settings.xml：在 Maven 设置页指定 User settings file（如 ~/.m2/settings.xml），尤其用了私有仓库或镜像
- 多模块项目构建慢？在 Maven Runner 里勾选 Always update snapshots 或调大 JVM Options for importer（如 -Xmx2g）
- Gradle 构建卡住？检查 Gradle JVM 是否匹配，禁用 Use Gradle from wrapper（否则仍走项目下的 gradlew）
基本上就这些。配置本地 Build 工具不复杂，但容易忽略“取消 Delegate”这一步——它才是让 IDEA 真正交出构建控制权的关键开关。
