JavaFX应用使用GluonFX打包为原生镜像时全屏功能异常的解决方案

本文探讨了JavaFX应用在使用GluonFX打包为原生镜像（.exe）后，调用stage.setFullScreen(true)时抛出ClassNotFoundException的问题。该异常通常是由于GraalVM原生编译过程中未能正确包含反射调用的内部JavaFX类所致。文章提供了两种解决方案：通过禁用全屏退出组合键作为临时规避，以及推荐通过在pom.xml中配置ReflectionList来明确指示GraalVM包含相关类，从而彻底解决此问题并保持默认的全屏行为。

引言

在使用javafx开发桌面应用时，将应用打包为原生可执行文件（如windows下的.exe）是常见的需求。gluonfx maven插件结合graalvm native image技术提供了便捷的解决方案。然而，开发者在这一过程中可能会遇到一些运行时异常，尤其是在涉及javafx的特定内部机制时。一个典型的问题是，当尝试通过stage.setfullscreen(true)将javafx stage设置为全屏模式时，打包后的原生应用会抛出java.lang.classnotfoundexception: com.sun.javafx.tk.quantum.overlaywarning异常，导致程序崩溃，而同一应用在通过javafx:run运行时却能正常工作。

问题分析：ClassNotFoundException的根源

这个ClassNotFoundException的出现，是GraalVM Native Image编译机制的一个典型表现。GraalVM在编译Java应用为原生镜像时，会进行积极的静态分析和代码剪枝，以减小最终可执行文件的大小并提高启动速度。它会尝试识别所有在运行时可能被调用的类、方法和字段，并只包含这些必需的部分。

然而，JavaFX的一些内部组件，特别是那些用于处理系统级交互或警告的辅助类（如com.sun.javafx.tk.quantum.OverlayWarning），可能并非通过直接的代码引用而是通过反射机制动态加载。GraalVM的静态分析器可能无法自动识别这些反射调用，从而在原生镜像中遗漏了这些关键类。当应用尝试在运行时通过反射加载这些缺失的类时，就会导致ClassNotFoundException。

日志中的关键信息如下：

Caused by: java.lang.AssertionError: java.lang.ClassNotFoundException: com.sun.javafx.tk.quantum.OverlayWarning     at com.sun.javafx.util.Utils.forceInit(Utils.java:869)     at com.sun.javafx.tk.quantum.OverlayWarningHelper.<clinit>(OverlayWarningHelper.java:44)     at com.sun.javafx.tk.quantum.OverlayWarning.<clinit>(OverlayWarning.java:50)     at com.sun.javafx.tk.quantum.windowStage.applyFullScreen(windowstage.java:685)     at com.sun.javafx.tk.quantum.WindowStage.setFullScreen(WindowStage.java:734)     ... (后续堆栈跟踪)

这清楚地表明，异常发生在setFullScreen方法内部，并且直接指向了OverlayWarning类的缺失。

立即学习“Java免费学习笔记（深入）”；

解决方案一：禁用全屏退出组合键（规避方法）

一个简单的规避方法是禁用JavaFX全屏模式下的默认退出组合键。JavaFX在进入全屏模式时，通常会显示一个提示用户如何退出全屏的浮层警告（OverlayWarning）。如果这个警告机制的内部类缺失，那么禁用它可能绕过这个异常。

通过在调用setFullScreen(true)之前设置setFullScreenExitKeyCombination(KeyCombination.NO_MATCH)，可以阻止JavaFX显示这个警告浮层，从而避免触发对OverlayWarning类的加载。

示例代码：

import javafx.application.Application; import javafx.scene.Scene; import javafx.scene.control.Button; import javafx.scene.layout.StackPane; import javafx.scene.input.KeyCombination; // 导入KeyCombination import javafx.stage.Stage;  public class FullScreenApp extends Application {      @Override     public void start(Stage stage) {         Button btn = new Button("Toggle Full Screen");         btn.setOnAction(event -> {             stage.setFullScreen(!stage.isFullScreen());         });          StackPane root = new StackPane(btn);         Scene scene = new Scene(root, 800, 600);          stage.setTitle("Full Screen Demo");         stage.setScene(scene);          // 禁用全屏退出组合键         stage.setFullScreenExitKeyCombination(KeyCombination.NO_MATCH);          // 尝试设置为全屏         stage.setFullScreen(true); // 现在应该不会抛出异常          stage.show();     }      public static void main(String[] args) {         launch();     } }

注意事项： 这种方法虽然能够解决ClassNotFoundException，但它改变了JavaFX全屏模式的默认行为。用户将无法通过默认的ESC键或其他组合键退出全屏，除非应用内部提供了退出全屏的逻辑。因此，这通常被视为一种临时或权宜之计。

解决方案二：配置GluonFX的反射列表（推荐方法）

最根本且推荐的解决方案是明确告知GraalVM Native Image构建工具，com.sun.javafx.tk.quantum.OverlayWarning类需要被包含在原生镜像中，即使它只通过反射方式访问。这可以通过在pom.xml文件中GluonFX插件的配置中添加reflectionList来实现。

AppMall应用商店

AI应用商店，提供即时交付、按需付费的人工智能应用服务

56

查看详情

在gluonfx-maven-plugin的<configuration>块中，添加<reflectionList>标签，并列出需要反射支持的完整类名。

pom.xml配置示例：

<plugin>     <groupId>com.gluonhq</groupId>     <artifactId>gluonfx-maven-plugin</artifactId>     <version>1.0.16</version> <!-- 请使用最新稳定版本 -->     <configuration>         <mainClass>fr.icom.info.m1.balleauprisonnier_fx.App</mainClass>         <reflectionList>             <!-- 明确指定需要通过反射加载的类 -->             <reflection>com.sun.javafx.tk.quantum.OverlayWarning</reflection>         </reflectionList>         <!-- 其他配置... -->     </configuration> </plugin>

配置说明：

• <reflectionList>：这是一个包含所有需要反射支持的类、方法或字段的列表。
• <reflection>：每个<reflection>标签内指定一个完整的类名。
• com.sun.javafx.tk.quantum.OverlayWarning：这是导致ClassNotFoundException的缺失类。将其添加到reflectionList后，GraalVM会在构建原生镜像时确保该类及其相关依赖被正确包含。

优点：

• 保持默认行为： 这种方法不会改变JavaFX全屏功能的默认行为，用户仍然可以通过ESC键或其他系统默认方式退出全屏，并且全屏警告浮层也能正常显示。
• 根本解决： 从根本上解决了由于GraalVM静态分析不足导致的类缺失问题。
• 专业性： 这是处理GraalVM Native Image中反射相关问题的标准方法。

构建与测试

完成pom.xml配置后，需要重新执行GluonFX的构建命令来生成新的原生可执行文件：

mvn gluonfx:build

然后，可以通过gluonfx:nativerun命令或直接运行生成的.exe文件来测试应用。此时，stage.setFullScreen(true)应该能够正常工作，不再抛出ClassNotFoundException。

总结

在JavaFX应用使用GluonFX打包为原生镜像时，遇到ClassNotFoundException，特别是涉及JavaFX内部类时，通常意味着GraalVM的静态分析未能捕获到通过反射加载的类。对于stage.setFullScreen(true)引发的com.sun.javafx.tk.quantum.OverlayWarning缺失问题，最稳健和推荐的解决方案是在pom.xml的gluonfx-maven-plugin配置中，通过<reflectionList>明确指定该类。这不仅能解决运行时异常，还能确保JavaFX全屏功能的完整性和默认用户体验。在开发原生JavaFX应用时，理解并善用GraalVM的反射配置机制是解决此类问题的关键。