Java 中 Jar 包内资源路径加载失败的完整解决方案

IntelliJ 中能正常加载图片，但打包成 Jar 后 getResource() 返回 null？根本原因在于：资源未被正确包含进 Jar 包——IDE 的类路径配置 ≠ 构建工具的资源打包逻辑。本文详解 Ma ven 资源配置、路径获取最佳实践及常见陷阱。

先聊一个很常见的场景：你在 IntelliJ IDEA 里调试 Ja va 桌面应用（比如用 Jaylib 做个小游戏），加载图片、音频什么的都好好的，结果一打成可执行 Jar，程序直接崩了——getResource() 返回 null，或者日志里冒出一句 “No object found at location!”。别慌，这不是你的代码有 bug，问题出在构建流程和运行环境的差异上。

? 问题根源分析

IntelliJ 默认把 src/main/resources 以及你手动标记为 “Resources Root” 的目录自动加入 classpath，所以 getClass().getClassLoader().getResource("textures/player.png") 在 IDE 里能正常命中。但 Ma ven（或 Gradle）就不一样了——它默认只处理 src/main/resources 下的文件。如果你的图片放在 assets/、resources/images/ 或者其他自定义目录，并且没在 pom.xml 里明确声明，那这些文件根本不会跟着一起打进 Jar。

你给的堆栈里有个关键线索：

jdk.zipfs.ZipFileSystemProvider.getFileSystem(...) → Path.of(...) → ResourceLocation.getPath()

这说明程序已经进入了 Zip 文件系统（也就是 Jar 运行态），但 getResource() 还是返回 null——这几乎可以断定是资源缺失，不是路径写错了，而是资源压根就不在 Jar 里。

✅ 正确解决方案：显式配置 Ma ven 资源目录

在 pom.xml 的 节点里，加一个 块，把所有需要打包的资源路径都列清楚：

    
        
        
            src/main/resources
        
        
        
            src/main/assets
            
            
                **/*.png
                **/*.jpg
                **/*.wa v
            
        
        
        
            .
            
                logo.png
            
        
    
    
    
        
            org.apache.ma ven.plugins
            ma ven-jar-plugin
            3.4.0
            
                
                    
                        com.github.command17.mariomaker17.Main
                    
                
            
        
    

⚠️ 注意： 是相对于 pom.xml 所在目录的路径；务必确认该路径下真实存在目标文件（如 src/main/assets/textures/player.png）。

?️ 代码层最佳实践：安全获取资源路径

你代码里用的 ClassLoader.getSystemClassLoader().getResource() 其实有点隐患——系统类加载器不一定能访问模块内的资源（尤其在模块化 JDK 环境下）。建议统一改成当前类的类加载器，并且加上空值校验和调试提示：

@Nullable
public String getPath() {
    URL resource = getClass().getClassLoader().getResource(this.location);
    if (resource == null) {
        LOGGER.error("Resource not found: '{}'. Check if it's included in JAR (run 'jar -tf target/your-app.jar | grep {}').",
                      this.location, this.location);
        return null;
    }
    try {
        // ⚠️ 关键：避免对 jar:// URL 使用 Path.of(URI) —— ZipFileSystem 不支持 URI 方案解析
        // 推荐：直接返回 URL 字符串，或使用 Files.readAllBytes(resource.openStream())
        return resource.toExternalForm(); // 如需文件系统路径，应解压到临时目录再处理
    } catch (IOException e) {
        LOGGER.error("Failed to read resource: {}", this.location, e);
        return null;
    }
}

✅ 更健壮的资源读取方式（推荐用于图像加载）：

public BufferedImage loadImage() {
    try (InputStream is = getClass().getClassLoader().getResourceAsStream(this.location)) {
        if (is == null) {
            throw new RuntimeException("Resource not found: " + this.location);
        }
        return ImageIO.read(is); // Jaylib 通常也支持 InputStream 构造
    } catch (IOException e) {
        throw new RuntimeException("Failed to load image: " + this.location, e);
    }
}

? 验证与调试技巧

1. 检查 Jar 内容：构建后执行

   jar -tf target/mariomaker17-1.0.jar | grep "player.png"

   确保输出包含对应路径（如 assets/textures/player.png）。

2. IDEA 同步检查：修改 pom.xml 后，点击右上角 Ma ven 工具栏 → Reload project，确保资源目录被识别。

3. 避免绝对路径陷阱：this.location 应为类路径相对路径（如 "textures/player.png"），不要以 / 开头（"/textures/player.png" 会被 ClassLoader.getResource() 忽略前导 /）。

✅ 总结

遵循以上步骤，就能彻底解决 “IDEA 能跑，Jar 报错” 这个老毛病，让你的应用在任何环境下都能稳稳加载资源。