使用jlink打包后如何获取JavaFX应用的资源路径？

问题场景 #

使用Maven+Visual Studio Code将JavaFX应用通过jlink打包为可执行程序，打包后的启动器可以运行，但启动后立即抛出NullPointerException：Cannot invoke "Object.toString()" because the return value of "java.lang.Class.getResource(String)" is null。

开发环境中通过Class.getResource获取资源目录路径正常，但打包后失效。资源文件（样式表、图片、音频）均放置在src/main/resources下的对应子目录中。

项目目录结构 #

|
|--src/main
|  |
|  |-- java
|  |   | ...
|  |
|  |-- resources
|      |
|      |-- img
|      |   | ...    
|      |
|      |-- style
|      |   | ...
|      |
|      |-- sound
|          | ...
|
|-- target
    |
    |-- classes
    |   | ...
    |   |
    |   |-- img
    |   |   | ...
    |   |
    |   |-- style
    |   |   | ...
    |   |
    |   |-- sound
    |   |   | ...
    |
    |-- ...
    |
    |-- app
        |
        |-- bin
        |-- ...

原资源获取代码 #

public static final String PATH_TO_STYLESHEET = App.class.getResource("/style").toString();
public static final String PATH_TO_IMG = App.class.getResource("/img").toString();
public static final String PATH_TO_SOUNDS = App.class.getResource("/sounds").toString();

pom.xml配置 #

<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 http://maven.apache.org/maven-v4_0_0.xsd">
    
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.openjfx</groupId>
    <artifactId>App</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.release>19</maven.compiler.release>
        <javafx.version>19</javafx.version>
        <javafx.maven.plugin.version>0.0.8</javafx.maven.plugin.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-controls</artifactId>
            <version>${javafx.version}</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-media</artifactId>
            <version>${javafx.version}</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-fxml</artifactId>
            <version>${javafx.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <release>${maven.compiler.release}</release>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.openjfx</groupId>
                <artifactId>javafx-maven-plugin</artifactId>
                <version>${javafx.maven.plugin.version}</version>
                <configuration>
                    <release>${maven.compiler.release}</release>
                    <jlinkImageName>App</jlinkImageName>
                    <launcher>launcher</launcher>
                    <mainClass>com.test.App</mainClass>
                </configuration>
            </plugin>
        </plugins>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
            </resource>
        </resources>
    </build>
    
</project>

打包命令 #

mvn javafx:jlink -f pom.xml

解决方案 #

1. 修正资源路径获取逻辑 #

jlink打包后，资源目录不会被作为独立资源保留，只能直接访问具体的资源文件，而非目录。修改代码为指向具体文件：

// 样式表示例
public static final String PATH_TO_STYLESHEET = App.class.getResource("/style/main.css").toString();
// 图片示例
public static final String PATH_TO_IMG = App.class.getResource("/img/icon.png").toString();
// 音频示例
public static final String PATH_TO_SOUNDS = App.class.getResource("/sound/bgm.mp3").toString();

如果需要批量获取目录下的资源，可通过ClassLoader.getResources()枚举资源（需处理URL连接），或在开发阶段预定义所有资源路径。

2. 确保资源被正确打包 #

你的pom.xml已配置resources节点，能确保资源被复制到target/classes，jlink会自动将这些资源合并到模块化镜像中，无需额外配置。

3. 可选：将资源复制到外部目录 #

若希望资源暴露在镜像外部（方便用户修改），可通过maven-resources-plugin将资源复制到jlink镜像的指定目录：

1. 在pom.xml的build/plugins中添加插件配置：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <version>3.3.1</version>
    <executions>
        <execution>
            <id>copy-resources</id>
            <phase>package</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
                <outputDirectory>${project.build.directory}/App/resources</outputDirectory>
                <resources>
                    <resource>
                        <directory>src/main/resources</directory>
                        <filtering>false</filtering>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>

2. 代码中通过相对路径访问外部资源：

String resourceDir = new File("resources").getAbsolutePath();
// 样式表路径示例
String stylesheetUrl = "file:///" + resourceDir + "/style/main.css";

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