JavaFX音频播放器仅在JAR包中抛出MediaException问题排查

1. 先修复NullPointerException（触发FXML加载失败的直接原因） #

报错栈显示NullPointerException出现在Controller.initialize(Controller.java:35)，结合你的AudioPlayer代码，根源是dir.listFiles()可能返回null，但你直接将其传入Arrays.asList()并添加到songsArray：

• 当dir.listFiles()返回null时，Arrays.asList(null)会生成一个包含null元素的列表，导致songsArray不为空
• 后续调用songsArray.get(0).toURI()时，因为元素是null，直接抛出NPE

修复代码：

public AudioPlayer(String audioFolderPath) throws Exception {
    File dir = new File(audioFolderPath);
    if (!dir.exists()) {
        if (!dir.mkdir())
            throw new Exception("Impossibile creare la cartella Sound");
    }
    // 先验证路径是否为目录
    if (!dir.isDirectory()) {
        throw new Exception("指定路径不是目录");
    }

    this.songsArray = new ArrayList<>();
    File[] files = dir.listFiles();
    // 仅当文件列表不为null时才添加
    if (files != null) {
        this.songsArray.addAll(Arrays.asList(files));
    }

    if (!this.songsArray.isEmpty()) {
        this.media = new Media(songsArray.get(0).toURI().toString());
        this.mediaPlayer = new MediaPlayer(media);
    } else {
        this.media = null;
        this.mediaPlayer = null;
    }
}

2. 解决MediaException（无法创建播放器的核心问题） #

JavaFX 11+是模块化框架，普通jar打包不会自动包含Media模块依赖的原生系统库（比如Windows下的dll文件），这是IDE运行正常但JAR运行失败的关键原因：

• IDE会自动配置JavaFX的模块路径和原生库路径，而直接运行JAR时没有这些配置

可选解决方案： #

• 方案一：命令行指定JavaFX模块路径运行
  确保你有JavaFX 11 SDK，运行JAR时添加模块参数：

  java --module-path "C:/path/to/javafx-sdk-11/lib" --add-modules javafx.controls,javafx.fxml,javafx.media -jar Demo-jar.jar
  

  替换C:/path/to/javafx-sdk-11/lib为你实际的JavaFX SDK lib目录路径。

• 方案二：用jpackage打包成Windows可执行文件（推荐）
  jpackage会自动打包JavaFX的依赖和原生库，生成独立的exe程序，无需用户额外配置JavaFX环境：

  1. 确保项目包含module-info.java并编译为模块化JAR
  2. 运行jpackage命令（示例）：

     jpackage --name AudioPlayer --module-path "C:/path/to/javafx-sdk-11/lib;./target" --module com.example.demo/com.example.demo.App --type exe
     

• 方案三：用jlink创建自定义运行时镜像
  生成包含JavaFX模块的自定义JRE，然后用该JRE运行你的JAR。

3. 修正Media的URI格式问题 #

你尝试的绝对路径URI格式有误，Windows下正确的file URI需要三个斜杠：

// 错误格式
this.media = new Media("file:/C:/Sound/Campanello_Casa.mp3");
// 正确格式
this.media = new Media("file:///C:/Sound/Campanello_Casa.mp3");

或者直接使用File.toURI().toString()，这个方法会自动生成正确格式的URI，避免手动拼接出错。

4. 路径环境排查 #

• 打包后运行时，程序的当前工作目录可能和IDE中不同，如果audioFolderPath是相对路径，会导致找不到目录，建议始终使用绝对路径，或者让用户通过配置指定音频目录。
• 再次确认音频目录和文件的权限：即使你认为有权限，也要确保运行JAR的用户（比如普通用户）确实有读取该目录和文件的权限。

内容的提问来源于stack exchange，提问作者Francesco Della Maggiora