JavaFX按钮打开新FXML窗口报LoadException的原因排查

以下是针对该错误的核心排查方向，按出现概率排序：

1. FXML文件路径不匹配 #

• 检查FXMLLoader.load()的路径写法：
  • 用getClass().getResource("path-window.fxml")时，路径是相对于当前控制器类的包路径；
  • 用getClass().getClassLoader().getResource("path-window.fxml")时，路径是相对于项目资源根目录（比如src/main/resources）。
• 路径区分大小写，且如果FXML在资源根目录，要加前置斜杠，比如"/path-window.fxml"，避免找不到文件。

2. FXML语法或配置错误 #

• 检查fx:controller属性：必须填写控制器的完整全类名（包名+类名），比如com.example.NewWindowController，不能漏写包名或写错类名。
• 检查标签闭合：所有FXML标签必须正确闭合，比如<Button>要对应</Button>，自闭合标签要写对格式（如<Label text="测试"/>）。
• 检查控件ID与控制器变量匹配：FXML中定义的fx:id（如#submitBtn）必须和控制器里@FXML注解的变量名完全一致（大小写敏感）。

3. 控制器类不符合要求 #

• 控制器必须是public访问权限，且必须有无参构造函数（如果自定义了带参构造，必须显式添加无参构造，JavaFX默认通过无参构造实例化控制器）。
• 控制器中用@FXML注解的变量不能是static类型，必须是非静态成员变量。

4. 文件或打包问题 #

• 确认path-window.fxml文件未被误删、内容未损坏（比如乱码、特殊字符）。
• Maven/Gradle项目需确保FXML文件在src/main/resources目录下，否则需要在构建配置中添加资源过滤，保证文件被打包到classpath中。

参考正确实现示例 #

打开新窗口的控制器代码：

@FXML
private void openNewWindow(ActionEvent event) {
    try {
        FXMLLoader loader = new FXMLLoader(getClass().getResource("/path-window.fxml"));
        Parent root = loader.load();
        Stage newStage = new Stage();
        newStage.setScene(new Scene(root));
        newStage.setTitle("新窗口");
        newStage.show();
    } catch (IOException e) {
        e.printStackTrace(); // 打印完整栈轨迹，可获取更详细错误信息
    }
}

对应的path-window.fxml片段：

<?xml version="1.0" encoding="UTF-8"?>
<?import javafx.scene.layout.VBox?>
<?import javafx.scene.control.Label?>

<VBox xmlns:fx="http://javafx.com/fxml" fx:controller="com.example.NewWindowController">
    <Label text="新窗口内容"/>
</VBox>

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