Java ServiceLoader无法找到类：Jogamp Java3D打包Jar后排查求助

在Jogamp Java3D的Font3D类中有如下代码：

final ServiceLoader<GeometryService> gsLoader = ServiceLoader.load(GeometryService.class);

final Iterator<GeometryService> iter = gsLoader.iterator();
if (iter.hasNext()) return iter.next();

throw new IllegalStateException("No GeometryService implementation");

这段代码在Eclipse中运行正常，但将项目打包为Jar文件后执行失败，抛出No GeometryService implementation异常。本人对Java的ServiceLoader技术毫无经验，直到几天前才听说，请问如何调试该问题？如何查看ServiceLoader的查找路径以及无法找到类的原因？

调试与排查方法 #

1. 检查Jar内的服务配置文件 #

ServiceLoader依赖META-INF/services/目录下的配置文件定位实现类：

• 配置文件名必须是服务接口的全限定类名（比如org.jogamp.java3d.GeometryService）
• 文件内容是实现类的全限定类名，每行一个
• 解压打包后的Jar，确认该配置文件存在、路径正确，且文件内的类名拼写无误，对应的实现类也在Jar包中

2. 开启ServiceLoader调试日志 #

通过Java系统属性打印加载细节，运行Jar时添加以下参数：

java -Dsun.misc.Service.level=FINEST -Djava.util.logging.ConsoleHandler.level=FINEST -jar your-app.jar

控制台会输出ServiceLoader的完整扫描过程，包括：扫描了哪些Jar包、读取了哪些配置文件、加载类时的错误信息（比如类找不到、类加载冲突）。

3. 手动验证类路径与加载能力 #

在代码中添加临时调试代码，直接验证类加载情况：

// 打印当前类路径
System.out.println("当前类路径: " + System.getProperty("java.class.path"));

// 尝试手动加载实现类
try {
    // 替换为实际的GeometryService实现类全限定名
    Class<?> implClass = Class.forName("org.jogamp.java3d.impl.GeometryServiceImpl", 
                                       true, 
                                       Thread.currentThread().getContextClassLoader());
    System.out.println("成功加载实现类: " + implClass.getName());
} catch (ClassNotFoundException e) {
    e.printStackTrace();
}

这段代码能帮你确认：实现类是否在类路径中，当前类加载器是否能正常加载它。

4. 检查打包配置 #

如果用Maven/Gradle打包，注意以下几点：

• 确保META-INF/services/下的配置文件被正确打包，没有被插件（比如maven-shade-plugin）忽略或覆盖
• 多模块项目中，实现类所在的模块是否被正确依赖并合并到最终Jar中
• 若存在多个Jar包含同名称的服务配置文件，检查是否被打包工具覆盖，导致正确的实现类配置丢失

5. 确认类加载器一致性 #

Eclipse运行时和Jar运行时的类加载器存在差异：

• Eclipse用自定义类加载器加载项目所有类，而Jar运行时默认用系统类加载器
• 确保GeometryService接口和它的实现类由同一个类加载器加载，否则ServiceLoader会判定实现类不属于该接口的实现

内容的提问来源于stack exchange，提问作者UnixNerd