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 规则存放位置
| 类型 | 位置 | 作用域 | 版本控制 |
|---|---|---|---|
| 项目级 | 仓库根目录.codebuddy/rules/<规则名>/RULE.mdc | 仅当前仓库，随 Git 共享 | 受 Git 跟踪 |
| 用户级 | 用户目录下规则文件 | 跨所有项目全局生效 | 不进版本库 |
本场景推荐项目级规则：团队拉下代码即生效，统一构建环境。
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 官方工具链机制：
- 在
~/.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>- 在 pom 中启用
maven-toolchains-plugin并指定<release>17</release>/<maven.compiler.release>17</maven.compiler.release>。 - 此后
mvn会自动用toolchains.xml里的 JDK17 编译，与JAVA_HOME解耦。
注意：toolchains 只影响Maven 编译用的 JDK，不影响 Maven 自身启动 JVM（Maven 启动仍用
JAVA_HOME）。若 Maven 启动也要 JDK17，仍需build.bat或改JAVA_HOME。
五、使用与生效要点
- 规则创建/修改后，必须新建对话会话才生效（当前会话不会自动重新加载规则）。
- 让 AI 编译或新建工程时，它会按规则执行
build.bat clean compile（而非直接mvn）。 - 你手动构建时同样直接
.\build.bat clean compile即可，无需关心系统 JDK。 - 可在对话中问 AI「当前应用了哪些规则？」来确认规则已加载。
- 规则正文建议控制在 500 行以内，避免模糊表述。
- 项目根目录的纯文本
CODEBUDDY.md也可放简单指令，但无元数据、不能细分触发类型，复杂规范仍建议用.codebuddy/rules下的RULE.mdc。
六、指令与文件速查表
| 项 | 内容 |
|---|---|
| 规则文件 | .codebuddy/rules/build-env/RULE.mdc（alwaysApply: true） |
| 构建脚本 | 仓库根目录build.bat |
| JDK | D:\SoftWare\jdk\jdk17（版本 17） |
| Maven | D:\SoftWare\Maven\apache-maven-3.6.3\bin\mvn.cmd |
| 本地仓库 | D:\software\Maven\repository |
| 编译命令 | build.bat clean compile |
| 避坑 | 禁止内联set JAVA_HOME；禁止直接mvn |
| 备选方案 | ~/.m2/toolchains.xml+maven-toolchains-plugin |
七、小结
要让 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」的目标。