maven-shade-plugin警告及shade-jar启动失败问题求助

问题详情 #

使用maven-shade-plugin打包JavaFX应用时收到以下警告：

javafx-controls-18.0.1-win.jar、javafx-graphics-18.0.1-win.jar、javafx-media-18.0.1-win.jar、javafx-web-18.0.1-win.jar存在1个重叠资源：

• META-INF/substrate/config/resourcebundles
  javafx-graphics-18.0.1-win.jar、javafx-media-18.0.1-win.jar、javafx-web-18.0.1-win.jar存在2个重叠资源：
• META-INF/substrate/config/jniconfig-x86_64-linux.json
• META-INF/substrate/config/reflectionconfig-x86_64-linux.json
  javafx-base-18.0.1-win.jar、javafx-controls-18.0.1-win.jar、javafx-graphics-18.0.1-win.jar存在1个重叠资源：
• META-INF/substrate/config/reflectionconfig.json
  maven-shade-plugin检测到部分类文件存在于多个JAR中。出现这种情况时，只有一个版本的类会被复制到uber jar中。通常这并无危害，您可以忽略这些警告；否则请根据mvn dependency:tree -Ddetail=true命令结果及上述输出手动排除构件。

尝试用以下配置过滤META-INF文件修复警告，但未生效：

<filters>
    <filter>
        <artifact>*:*</artifact>
        <excludes>
           <exclude>META-INF/*</exclude>
        </excludes>
    </filter>
</filters>

更关键的是，打包后的shade jar无法启动，报错：

Error: JavaFX runtime components are missing, and are required to run this application

当前pom.xml配置如下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.test</groupId>
    <artifactId>TEST</artifactId>
    <version>1.0</version>
    <name>TEST</name>

    <packaging>jar</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <junit.version>5.8.2</junit.version>
        <javafx.version>18.0.1</javafx.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-controls</artifactId>
            <version>${javafx.version}</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-web</artifactId>
            <version>${javafx.version}</version>
        </dependency>
        <dependency>
            <groupId>uk.co.caprica</groupId>
            <artifactId>vlcj</artifactId>
            <version>4.7.1</version>
        </dependency>
        <dependency>
            <groupId>uk.co.caprica</groupId>
            <artifactId>vlcj-javafx</artifactId>
            <version>1.1.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.4.0</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <transformers>
                                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                                    <mainClass>com.test.Main</mainClass>
                                </transformer>
                            </transformers>
                            <filters>
                                <filter>
                                    <artifact>*:*</artifact>
                                    <excludes>
                                        <exclude>META-INF/*</exclude>
                                    </excludes>
                                </filter>
                            </filters>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.10.1</version>
                <configuration>
                    <forceJavacCompilerUse>true</forceJavacCompilerUse>
                    <source>18</source>
                    <target>18</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.2.2</version>
            </plugin>
            <plugin>
                <groupId>org.openjfx</groupId>
                <artifactId>javafx-maven-plugin</artifactId>
                <version>0.0.8</version>
                <executions>
                    <execution>
                        <id>default-cli</id>
                        <configuration>
                            <mainClass>com.test/com.test.Main</mainClass>
                            <launcher>TEST</launcher>
                            <jlinkZipName>TEST</jlinkZipName>
                            <jlinkImageName>TEST</jlinkImageName>
                            <noManPages>true</noManPages>
                            <stripDebug>true</stripDebug>
                            <noHeaderFiles>true</noHeaderFiles>
                            <compress>2</compress>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

解决方案 #

1. 调整Shade插件过滤规则，仅排除冲突资源 #

之前的配置排除了所有META-INF内容，导致JavaFX运行时必要的配置丢失。只需针对性排除重叠的substrate配置文件：

<filters>
    <filter>
        <artifact>org.openjfx:*</artifact>
        <excludes>
            <exclude>META-INF/substrate/config/resourcebundles</exclude>
            <exclude>META-INF/substrate/config/jniconfig-x86_64-linux.json</exclude>
            <exclude>META-INF/substrate/config/reflectionconfig-x86_64-linux.json</exclude>
            <exclude>META-INF/substrate/config/reflectionconfig.json</exclude>
        </excludes>
    </filter>
</filters>

2. 添加JavaFX模块信息Transformer #

JavaFX是模块化框架，需保留模块信息才能被运行时识别，在Shade插件的transformers中添加：

<transformers>
    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
        <mainClass>com.test.Main</mainClass>
    </transformer>
    <transformer implementation="org.apache.maven.plugins.shade.resource.ModulesResourceTransformer"/>
</transformers>

3. 为JavaFX依赖添加平台分类器 #

当前依赖未指定平台分类器，导致打包时缺失平台相关原生库。以Windows平台为例，修改JavaFX依赖：

<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-controls</artifactId>
    <version>${javafx.version}</version>
    <classifier>win</classifier>
</dependency>
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-web</artifactId>
    <version>${javafx.version}</version>
    <classifier>win</classifier>
</dependency>

如果需要跨平台打包，可通过Maven Profile分别配置不同平台的分类器。

4. 最终修正后的maven-shade-plugin配置 #

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.4.0</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>com.test.Main</mainClass>
                    </transformer>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ModulesResourceTransformer"/>
                </transformers>
                <filters>
                    <filter>
                        <artifact>org.openjfx:*</artifact>
                        <excludes>
                            <exclude>META-INF/substrate/config/resourcebundles</exclude>
                            <exclude>META-INF/substrate/config/jniconfig-x86_64-linux.json</exclude>
                            <exclude>META-INF/substrate/config/reflectionconfig-x86_64-linux.json</exclude>
                            <exclude>META-INF/substrate/config/reflectionconfig.json</exclude>
                        </excludes>
                    </filter>
                </filters>
            </configuration>
        </execution>
    </executions>
</plugin>

关键说明 #

• 重叠资源警告来自JavaFX各模块共享的substrate配置文件，这些文件对普通Jar运行无影响，只需排除冲突项即可，无需删除全部META-INF内容。
• JavaFX作为模块化框架，必须保留模块信息，否则运行时无法识别组件。
• 必须包含对应平台的JavaFX原生库，否则会出现运行时组件缺失错误。

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