CodeBuddy 指定 JDK 与 Maven 版本/路径：场景、配置方式与指令详解

CodeBuddy 指定 JDK 与 Maven 版本/路径：场景、配置方式与指令详解

适用场景：在本机「系统默认 JDK 不是目标版本」的情况下，希望 CodeBuddy（AI 助手）在新建项目或实现/编译代码时，始终使用指定版本与路径的 JDK 和 Maven，不再被系统环境干扰。

一、为什么需要专门配置

CodeBuddy 本身没有独立的「指定 JDK/Maven 物理路径」设置项（官方文档的 Integration 只负责 Supabase / CloudBase 等云服务接入）。能约束 AI 行为、让它「每次都按指定环境来」的机制是Rules（规则）。

但规则只是「给 AI 的系统级指令」，它不能真正改变 IDE/终端实际使用的 JVM。真正影响编译结果的是执行命令时的JAVA_HOME与PATH。因此稳健方案是：规则（告诉 AI 怎么做）+ 固定构建脚本（真正锁死环境）二合一。

本机典型痛点（以本文为例）

• 系统JAVA_HOME/PATH指向JDK8（C:\Program Files\Java\jdk1.8.0_202）。
• 项目需要JDK 17，安装在D:\SoftWare\jdk\jdk17。
• Maven 固定为D:\SoftWare\Maven\apache-maven-3.6.3。
• 本地仓库实际在D:\software\Maven\repository（C:\Users\admin\.m2\settings.xml的localRepository指定）。
• 直接mvn会因 JDK8 报无效的目标发行版: 17。
• 内联cmd /c "set \"JAVA_HOME=...\" & ..."在本机引号转义失效，JAVA_HOME仍残留 JDK8；只有写进.bat文件才能稳定生效。

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

二、配置方式一：Rules 规则（核心）

2.1 规则存放位置

本场景推荐项目级规则：团队拉下代码即生效，统一构建环境。

2.2 文件格式

规则文件 =YAML 前置元数据 + Markdown 正文：

--- description: 规则描述（用于 AI 判断相关性） alwaysApply: true # true=每次会话自动加载原文 enabled: true # 是否启用 updatedAt: 2026-07-16T00:00:00.000Z --- # 正文：给 AI 的具体指令/规范（纯 Markdown）

三种触发方式：

• 总是（Always）：alwaysApply: true，每个会话自动加载原文。
• 智能体请求（Agent Requested）：靠description让模型判断相关性，按需读取。
• 手动（Manual）：对话中@规则名提及才加载。

2.3 本项目实际使用的规则内容

文件：.codebuddy/rules/build-env/RULE.mdc

--- description: 统一构建环境规范（JDK17 与 Maven3.6.3） alwaysApply: true enabled: true --- # 本项目构建环境强制规范 - JDK 必须使用 **17**，路径固定 `D:\SoftWare\jdk\jdk17`。 - Maven 固定 `D:\SoftWare\Maven\apache-maven-3.6.3\bin\mvn`（apache-maven-3.6.3）。 - 本地 Maven 仓库实际在 `D:\software\Maven\repository`（由 `C:\Users\admin\.m2\settings.xml` 的 localRepository 指定）。 - **系统默认 `JAVA_HOME` 指向 JDK8**（`C:\Program Files\Java\jdk1.8.0_202`），不能直接用 `mvn`，必须先设 `JAVA_HOME=D:\SoftWare\jdk\jdk17`。 - 内联 `cmd /c "set \"JAVA_HOME=...\" & ..."` 在本机引号转义会失效（JAVA_HOME 仍残留 JDK8，报「无效的目标发行版:17」），**必须写进 `.bat` 文件再执行**。 - 所有编译/打包一律调用仓库根目录的 `build.bat`（已写死 JDK17 与 Maven 路径），不要直接手敲 `mvn` 或 `mvn.cmd`。 - 新建子工程时，pom 内 `<java.version>17</java.version>`（或 `<maven.compiler.source/target>17`），不要依赖系统默认 JDK。 - 技术栈参考：Spring Boot 3.4.5 + Spring AI 1.1.2 + Ollama 本地 `qwen2.5:7b-instruct`，包名 `com.casestudy.ai.*`。 - Spring AI 1.1.2 中 `QuestionAnswerAdvisor` 在包 `org.springframework.ai.chat.client.advisor.vectorstore`，且构造器为包私有，只能用 `QuestionAnswerAdvisor.builder(vectorStore).searchRequest(searchRequest).build()`；依赖 `artifactId=spring-ai-advisors-vector-store`。

三、配置方式二：固定构建脚本（真正锁死环境）

光有规则不够——AI 仍需执行一个「写死环境」的命令。仓库根目录放一个build.bat：

@echo off REM 统一构建脚本：写死 JDK17 与 Maven3.6.3 路径，避免系统 JDK8 干扰 set "JAVA_HOME=D:\SoftWare\jdk\jdk17" set "PATH=D:\SoftWare\jdk\jdk17\bin;%PATH%" set "M2=D:\SoftWare\Maven\apache-maven-3.6.3\bin" if "%1"=="" ( echo 用法: build.bat [maven 参数...] 例: build.bat clean compile "%M2%\mvn.cmd" -version ) else ( "%M2%\mvn.cmd" %* )

用法：build.bat clean compile、build.bat package、build.bat -version等，参数原样转发给 Maven。

为什么必须.bat而不是内联set

• ❌cmd /c "set \"JAVA_HOME=D:\SoftWare\jdk\jdk17\" & mvn ..."→ 转义引号在本机不生效，JAVA_HOME仍为 JDK8，报错无效的目标发行版: 17。
• ✅ 把set写进.bat文件再call build.bat→JAVA_HOME正确切换为 JDK17。
• 验证：build.bat -version应显示Java version: 17 ... runtime: D:\SoftWare\jdk\jdk17与Maven 3.6.3。

四、配置方式三（备选）：Maven toolchains.xml

若希望 Maven 自身按路径挑选 JDK（连build.bat都不必备），可用 Maven 官方工具链机制：

1. 在~/.m2/toolchains.xml声明 JDK 安装路径：

<toolchains><toolchain><type>jdk</type><provides><version>17</version><vendor>oracle</vendor></provides><configuration><jdkHome>D:\SoftWare\jdk\jdk17</jdkHome></configuration></toolchain></toolchains>

2. 在 pom 中启用maven-toolchains-plugin并指定<release>17</release>/<maven.compiler.release>17</maven.compiler.release>。
3. 此后mvn会自动用toolchains.xml里的 JDK17 编译，与JAVA_HOME解耦。

注意：toolchains 只影响Maven 编译用的 JDK，不影响 Maven 自身启动 JVM（Maven 启动仍用JAVA_HOME）。若 Maven 启动也要 JDK17，仍需build.bat或改JAVA_HOME。

五、使用与生效要点

1. 规则创建/修改后，必须新建对话会话才生效（当前会话不会自动重新加载规则）。
2. 让 AI 编译或新建工程时，它会按规则执行build.bat clean compile（而非直接mvn）。
3. 你手动构建时同样直接.\build.bat clean compile即可，无需关心系统 JDK。
4. 可在对话中问 AI「当前应用了哪些规则？」来确认规则已加载。
5. 规则正文建议控制在 500 行以内，避免模糊表述。
6. 项目根目录的纯文本CODEBUDDY.md也可放简单指令，但无元数据、不能细分触发类型，复杂规范仍建议用.codebuddy/rules下的RULE.mdc。

六、指令与文件速查表

七、小结

要让 CodeBuddy 在新建/编译项目时稳定使用指定 JDK 与 Maven，关键是**「规则约束 AI 行为 +.bat脚本锁死执行环境」**：

• Rules告诉 AI「必须用 JDK17 + 指定 Maven，且走build.bat」；
• build.bat在命令执行层面真正把JAVA_HOME/PATH切到 JDK17，绕开系统 JDK8 与内联set转义失效的坑；
• 如需更进一步解耦，可叠加Maven toolchains.xml。

这样就实现了「无论系统默认是什么，AI 生成的构建动作始终命中目标 JDK/Maven」的目标。