JavaFX MediaPlayer 播 MP3 需解决四大问题：① Java 11+ 需显式引入 javafx-media 和 javafx-controls 模块并配置启动参数；② Media 路径必须用 file.toURI().toString() 转合法 URI；③ UI 更新须用 Platform.runLater()；④ Linux/macOS 需安装 GStreamer 插件支持 MP3 解码。
JavaFX 自带的 MediaPlayer 和 MediaView 能播 MP3，但实际用起来会卡在几个关键点上：路径加载失败、UI 线程阻塞、进度条不同步、以及 Java 11+ 默认移除了 JavaFX 模块导致编译报错。下面直奔实操。
JavaFX 项目必须显式引入模块和依赖
Java 11 及以后版本不再内置 JavaFX，哪怕你装了 JDK，javafx.scene.media 也会报红。Maven 项目需在 pom.xml 中添加：
<dependency>
<groupId>org.openjfx</groupId>
<artifactId>javafx-media</artifactId>
<version>20</version>
</dependency>
<dependency>
<groupId>org.openjfx</groupId>
<artifactId>javafx-controls</artifactId>
<version>20</version>
</dependency>
同时启动命令要加模块参数，例如：
java --module-path %PATH_TO_JAVAFX% --add-modules javafx.controls,javafx.media -jar MusicPlayer.jar
- Windows 下
%PATH_TO_JAVAFX%是解压后的lib目录绝对路径 - IntelliJ 用户需在
Run Configuration → VM Options里手动填入模块参数 - 不加
--add-modules javafx.media，MediaPlayer类根本加载不到，会抛NoClassDefFoundError
Media 构造时路径必须是合法 URI，不能直接用相对路径字符串
写成 new Media("song.mp3") 几乎必失败——Media 构造函数只接受 URI 字符串，且对空格、中文、特殊字符极其敏感。正确做法是：
立即学习“Java免费学习笔记（深入）”；
- 用
Paths.get("song.mp3").toUri().toString()转换本地路径 - 确保文件存在且有读权限（尤其 macOS/Linux 下注意路径大小写）
- 避免使用
getClass().getResource()加载资源，它返回null时不会报错，只会静默失败
示例代码片段：
File file = new File("music/sample.mp3");
if (file.exists()) {
String uri = file.toURI().toString();
Media media = new Media(uri); // ✅ 正确
MediaPlayer player = new MediaPlayer(media);
}
播放控制必须用 Platform.runLater() 更新 UI 元素
MediaPlayer 的事件回调（如 setOnPlaying、setOnStopped）运行在后台线程，直接操作 Button.setText() 或 Slider.setValue() 会触发 IllegalStateException: Not on FX application thread。
- 所有 UI 更新必须包在
Platform.runLater(() -> { ... })里 - 进度条同步推荐用
Timeline定期拉取player.getCurrentTime()，而不是监听时间变化事件（该事件不保证实时） - 暂停/恢复后，
getCurrentTime()返回的是暂停时刻的时间戳，不是总时长百分比，需手动计算：player.getCurrentTime().toSeconds() / player.getTotalDuration().toSeconds()
MP3 解码依赖系统原生库，Linux/macOS 需额外安装 GStreamer 插件
Windows 上 JavaFX 内置了 MP3 支持，但 Linux（如 Ubuntu）和 macOS 默认无法播放 MP3，会静默失败或抛 MediaException: Could not create player。
- Ubuntu/Debian：安装
gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly - macOS：用 Homebrew 安装
gstreamer gst-plugins-bad gst-plugins-ugly - 验证方式：运行
gst-inspect-1.0 mpgaudioparse，有输出即插件就位 - 如果仍不行，可临时改用 WAV 格式测试逻辑——它不依赖额外插件
真正卡住人的从来不是“怎么写播放按钮”，而是路径转 URI 的细节、模块参数漏写、跨平台解码缺失这三处。跑通前先确认 JavaFX 模块加载成功、MP3 文件能被 URI 定位、GStreamer 插件已就位——其余都是常规 UI 交互逻辑。
