JavaFX 自 JDK 11 起需单独下载并显式配置模块路径，编译运行必须加 --module-path 和 --add-modules（如 javafx.controls），主类须继承 Application 并通过 launch() 启动，FXML 需正确配置资源路径与 module-info.java 中的 requires 和 opens 声明。
JavaFX 已不再随 JDK 默认捆绑（自 JDK 11 起），直接用 javac 编译或 java 运行含 JavaFX 的代码会报 NoClassDefFoundError: javafx/application/Application —— 这是绝大多数人卡住的第一步。
确认 JavaFX 是否可用，以及它在哪
不要假设系统里“有 JavaFX”。JDK 8–10 自带，JDK 11+ 需单独下载 SDK 并显式引入模块路径。
- 检查当前 JDK 版本：
java -version；若 ≥ 11，JavaFX 不在 classpath 也不在默认模块中 - 从 https://www.php.cn/link/f676fd7c5cadc839db8b7e65bfbdd8c6 下载对应平台的 JavaFX SDK（如
javafx-sdk-22.0.1） - 解压后记下路径，例如：
/path/to/javafx-sdk-22.0.1/lib—— 后续要用到这个lib目录
编译和运行 JavaFX 程序必须加 --module-path 和 --add-modules
JavaFX 是模块化设计，不加这两个参数，javac 能过，但 java 一定失败。常见错误包括：
-
Error: Could not find or load main class HelloApp（主类找不到，其实是模块加载失败的误导） java.lang.NoClassDefFoundError: javafx/application/Applicationjava.lang.IllegalAccessError: class HelloApp cannot access class com.sun.javafx.application.LauncherImpl
正确做法（以 HelloApp.java 为例）：
立即学习“Java免费学习笔记（深入）”；
javac --module-path /path/to/javafx-sdk-22.0.1/lib --add-modules javafx.controls,javafx.fxml HelloApp.java java --module-path /path/to/javafx-sdk-22.0.1/lib --add-modules javafx.controls,javafx.fxml HelloApp
注意：--add-modules 至少要包含 javafx.controls（按钮、文本框等控件基础），如果用了 FXML 还要加 javafx.fxml；其他如 javafx.web、javafx.media 按需添加。
main 方法不能直接 new Application，必须用 launch()
JavaFX 应用入口不是普通 Java 类的 static main 启动逻辑，而是由 JavaFX 自己的启动器接管。写错会导致：
- 空窗口一闪而过
-
IllegalStateException: Not on FX application thread（后续操作 UI 时爆发） - 程序不响应、按钮点不动
标准结构必须是：
public class HelloApp extends Application {
@Override
public void start(Stage stage) {
Button btn = new Button("Hello");
Scene scene = new Scene(new VBox(btn), 300, 200);
stage.setScene(scene);
stage.show();
}
public static void main(String[] args) {
launch(args); // ← 必须调用这个，不能 new HelloApp().start(...)
}
}
launch() 会初始化 FX 线程、注册事件循环，并调用 start()。绕过它等于跳过整个 JavaFX 生命周期管理。
FXML 加载失败常因路径、ClassLoader 或模块导出问题
用 FXMLLoader.load() 报 java.lang.NullPointerException 或 javafx.fxml.LoadException，90% 是资源路径不对或模块未导出包。
- FXML 文件必须放在 classpath 下（如
src/main/resources/view/main.fxml），加载时用getClass().getResource("/view/main.fxml")，开头斜杠不能漏 - 若用 Maven，确保
pom.xml中resources配置包含**/*.fxml - 模块描述符
module-info.java中需有：requires javafx.fxml;和opens your.package.name to javafx.fxml;（否则反射加载失败）
没写 opens 会导致 LoadException: Cannot resolve a binding for 'text' 类似错误，表面是绑定失败，实为模块封装拦截了字段访问。
JavaFX 的模块隔离和线程模型是硬性约束，不是可选项。漏掉 --module-path、少写一个 requires 或误用 Platform.runLater 的时机，都会让界面停在“能编译但不工作”的状态。调试时优先查这三处：模块参数、launch 调用、资源路径与模块 opens 声明。
