引言
在使用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.(OverlayWarningHelper.java:44)
at com.sun.javafx.tk.quantum.OverlayWarning.(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来实现。
在gluonfx-maven-plugin的
pom.xml配置示例：
com.gluonhq gluonfx-maven-plugin 1.0.16 fr.icom.info.m1.balleauprisonnier_fx.App com.sun.javafx.tk.quantum.OverlayWarning
配置说明：
：这是一个包含所有需要反射支持的类、方法或字段的列表。 ：每个 标签内指定一个完整的类名。 - 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配置中，通过
