Cannot determine path to 'tools.jar' for JDK 17

Question

在升级至JDK 17后，开发者常遇到“Cannot determine path to 'tools.jar'”错误，尤其是在使用依赖`tools.jar`的旧版构建工具（如某些Gradle插件或IDEA配置）时。该问题源于JDK 17已彻底移除`tools.jar`——自JDK 9起，其内容已被模块化整合进`jrt-fs.jar`和平台模块中。因此，构建系统无法定位该文件，导致编译或运行失败。解决此问题需更新工具链版本，替换对`tools.jar`的显式引用为模块路径方式，并确保使用的IDE和插件兼容JDK 17。

Answer 1

1. 问题背景与现象描述

在将Java开发环境从JDK 8升级至JDK 17的过程中，许多开发者频繁遇到如下错误信息：

Cannot determine path to 'tools.jar'

该错误通常出现在使用Gradle、Maven或IntelliJ IDEA等构建工具和IDE的项目中。尤其是那些依赖于tools.jar进行编译期操作（如字节码增强、注解处理、JDI调试支持）的旧版插件或自定义任务。

这一问题的根本原因在于：自JDK 9起，Java平台引入了模块化系统（JPMS），原有的tools.jar被拆分并整合进运行时镜像（jimage）和jrt-fs.jar中，不再以独立JAR文件形式存在。而JDK 17作为长期支持版本（LTS），彻底移除了对tools.jar的兼容性支持。

2. 技术演进路径分析

JDK 版本	tools.jar 状态	关键变化
JDK 8 及以下	存在且可访问	包含javac、javadoc、JDI等工具类
JDK 9 - 10	逻辑存在，但已模块化	整合进java.compiler, jdk.jdi等模块
JDK 11+	物理文件消失	通过jrt-fs.jar提供运行时访问
JDK 17 (LTS)	完全移除引用支持	构建系统需适配模块路径方式

3. 常见触发场景列举

• 使用老旧版本的Gradle（如 < 6.0）配合gradle-tooling-api插件
• IntelliJ IDEA 配置中显式引用$JAVA_HOME/lib/tools.jar
• Spring Boot 2.x + 自定义Agent注入逻辑
• Maven Compiler Plugin 使用非标准fork选项
• 第三方AOP框架（如AspectJ LTW）直接加载tools.jar
• 使用JavaAssist或ASM进行动态类生成时依赖JDK内部API
• CI/CD流水线中未同步更新构建节点JDK版本

4. 根本原因深度剖析

1. JDK 9之后采用Jigsaw模块系统，tools.jar中的类被分配到多个命名模块中，例如：
   • jdk.compiler —— 提供编译器API
   • jdk.javadoc —— Javadoc工具实现
   • jdk.jdi —— Java调试接口
2. 文件系统层面，JDK安装目录下的lib子目录不再包含tools.jar，而是通过jrt-fs.jar挂载一个虚拟文件系统来暴露模块内容。
3. 传统构建脚本通过硬编码路径（如${java.home}/../lib/tools.jar）探测该文件，导致在JDK 17环境下返回null或抛出异常。
4. 部分IDE插件未适配新的模块化结构，在启动时尝试加载不存在的JAR文件。

5. 解决方案体系化策略

graph TD
    A[检测到 Cannot determine path to 'tools.jar'] --> B{判断来源}
    B -->|Gradle项目| C[升级Gradle至7.4+]
    B -->|Maven项目| D[检查maven-compiler-plugin配置]
    B -->|IDEA报错| E[更新IDEA至2021.3+并清理缓存]
    B -->|自定义代码引用| F[替换为Module API或ToolProvider]
    C --> G[确认插件兼容性: spring-boot, mybatis-generator等]
    D --> H[设置<release>17</release>避免fork]
    E --> I[重置Project SDK指向JDK 17 Home]
    F --> J[使用ToolProvider.getSystemTool("javac")]

6. 具体修复示例与代码迁移

若原有代码中存在如下片段：

File toolsJar = new File(System.getProperty("java.home") + "/../lib/tools.jar");
URLClassLoader.newInstance(new URL[]{toolsJar.toURI().toURL()}, getClass().getClassLoader());

应改为基于标准API的方式：

import java.util.spi.ToolProvider;

public class CompilerInvoker {
    public static void invokeJavac(String... args) {
        ToolProvider.findFirst("javac")
            .ifPresentOrElse(
                tool -> tool.run(System.out, System.err, args),
                () -> System.err.println("javac tool not available")
            );
    }
}

此方法不依赖具体文件路径，而是通过服务发现机制获取内置工具，具备跨JDK版本兼容性。

7. 构建工具适配指南

工具类型	推荐最低版本	关键配置项
Gradle	7.4	sourceCompatibility = JavaVersion.VERSION_17
Maven	3.8.1	<maven.compiler.release>17</maven.compiler.release>
IntelliJ IDEA	2021.3	Settings → Build → Gradle → Gradle JVM 设置为17
Spring Boot	2.7.0	确保spring-boot-gradle-plugin支持Java 17