M1 Mac运行JavaFX打包JAR调用MediaPlayer报类未找到错误

报错java.lang.NoClassDefFoundError: javafx/scene/media/Media的核心原因是你打包生成的可执行JAR没有正确包含JavaFX Media模块的对应依赖，不同环境表现不一致的原因如下：

• VSCode中启动正常：IDE运行时会自动将项目配置的所有JavaFX模块加入运行时模块路径/类路径，不存在依赖缺失问题。
• 旧款Intel芯片iMac运行正常：之前的构建产物仅包含x86_64架构的JavaFX依赖，和Intel芯片匹配；M1系列属于arm64架构，架构不匹配的依赖无法被加载，再叠加打包配置的漏项，就会触发类找不到的错误。

1. 检查项目pom.xml的依赖配置，显式引入和你当前JavaFX版本完全一致的javafx-media依赖，并且指定对应Apple Silicon芯片的平台分类：

<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-media</artifactId>
    <version>17.0.2</version> <!-- 版本号和项目中其他javafx-*依赖完全统一 -->
    <classifier>mac-aarch64</classifier> <!-- M1/M2等Apple Silicon设备使用该值，Intel芯片Mac对应值为mac -->
</dependency>

*如果需要打出的JAR同时兼容Intel和Apple Silicon架构的Mac，同时引入mac、mac-aarch64两个分类的JavaFX依赖即可，运行时会自动匹配当前设备架构加载对应本地库。

2. 修正Maven打包插件配置，如果你使用maven-shade-plugin构建可执行胖JAR，必须添加SPI资源合并配置，避免JavaFX本地库加载逻辑失效，参考配置如下：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.4.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>替换为你项目的主类全限定名</mainClass>
                    </transformer>
                    <!-- 必须添加该配置合并服务描述文件，否则JavaFX媒体组件无法正常加载 -->
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
                <!-- 检查配置中没有exclude掉org.openjfx相关的包路径 -->
            </configuration>
        </execution>
    </executions>
</plugin>

如果你用的是javafx-maven-plugin打包镜像，直接在插件配置的jlink选项里把javafx.media加到需要包含的模块列表即可。

3. 执行mvn clean package命令重新构建，必须加clean参数清空target目录下的旧构建产物，避免旧的缓存文件导致打包不全。
4. 构建完成后可以解压生成的JAR包，检查是否存在javafx/scene/media/Media.class文件，以及对应mac-aarch64架构的libjfxmedia.dylib等本地库文件，确认依赖已正确打入包内再运行测试。

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