Java JAR 包資源文件讀取：ClassLoader.getResourceAsStream 統一解決開發與打包後路徑問題

核心問題

開發時 (IDE 運行) 文件在文件系統，相對路徑 `src/main/resources/image.png` 可用。
打包成 JAR 後，資源進入 JAR 內部，**不再是文件系統文件**，`File`/`FileInputStream` 失效，**必須用 `ClassLoader` 讀取流**。

統一解決方案：Thread.currentThread().getContextClassLoader()

public class ResourceUtil {
    /**
     * 統一獲取資源輸入流 (開發環境 + JAR 包均可用)
     * @param path 資源相對路徑 (如 "images/logo.png", "config/app.properties")
     * @return InputStream 或 null (未找到)
     */
    public static InputStream getResourceAsStream(String path) {
        // 1. 優先使用線程上下文類加載器 (支持 Web 容器、OSGi、線程隔離場景)
        ClassLoader cl = Thread.currentThread().getContextClassLoader();
        InputStream is = cl.getResourceAsStream(path);
        
        // 2. 回退到當前類加載器
        if (is == null) {
            is = ResourceUtil.class.getClassLoader().getResourceAsStream(path);
        }
        
        // 3. 最後嘗試當前類的類加載器 (相對路徑不以 / 開頭)
        if (is == null) {
            is = ResourceUtil.class.getResourceAsStream(path); // 相對當前類包路徑
        }
        return is;
    }
    
    // 便利方法：讀取 properties
    public static Properties loadProperties(String path) throws IOException {
        try (InputStream is = getResourceAsStream(path)) {
            if (is == null) throw new FileNotFoundException("Resource not found: " + path);
            Properties props = new Properties();
            props.load(is);
            return props;
        }
    }
    
    // 便利方法：讀取圖片 (Swing/JavaFX)
    public static Image loadImage(String path) {
        try (InputStream is = getResourceAsStream(path)) {
            if (is == null) return null;
            return ImageIO.read(is); // javax.imageio.ImageIO
        } catch (IOException e) {
            return null;
        }
    }
}

資源路徑規範

Maven 標準目錄結構 (資源自動打包)

src/
└── main/
    ├── java/
    │   └── com/example/App.java
    └── resources/          <-- 資源文件放這裡
        ├── config/
        │   └── app.properties
        └── images/
            └── logo.png

編譯後 `target/classes/config/app.properties`，打包進 `app.jar/config/app.properties`。
代碼中統一用 `ResourceUtil.getResourceAsStream("config/app.properties")`。

Spring Boot / 現代框架最佳實踐

@Component
public class ConfigLoader {
    @Value("classpath:config/app.properties") // Spring Resource 抽象
    private Resource resource;
    
    public Properties load() throws IOException {
        try (InputStream is = resource.getInputStream()) {
            Properties props = new Properties();
            props.load(is);
            return props;
        }
    }
}

避坑指南

1. 絕不使用 `new File("relative/path")` 讀取項目資源，打包後必失效。
2. 區分「加載類」與「線程上下文類加載器」：Web 容器 (Tomcat) 中線程上下文類加載器能訪問 WebApp 私有類/資源，更通用。
3. 資源文件名區分大小寫：Linux 容器/JAR 區分大小寫，Windows 不區分，**路徑字符串嚴格按實際文件名大小寫編寫**。
4. 大文件勿放入 JAR：超過幾 MB 的資源 (視頻、大模型) 應外部化存儲 (配置中心、對象存儲、掛載卷)，JAR 只放配置、小圖標、模板。

總結

**`ClassLoader.getResourceAsStream("相對路徑")` 是讀取 JAR 內資源的唯一正解**。封裝工具類統一入口，資源放 `src/main/resources`，開發、測試、打包、部署全環境通用。