通过System.load加载OpenCV在Windows失败，Linux正常问题排查

问题背景 #

我开发了一款集成OpenCV的单可执行Jar应用，为避免终端用户自行下载OpenCV，将OpenCV二进制文件打包进Jar内，提取至临时文件后通过System.load()加载。Linux环境加载opencv_490.so正常，但Windows环境加载opencv_490.dll时触发UnsatisfiedLinkError，报错提示找不到依赖库，且已确认临时文件生成并写入成功。

原实现代码 #

public class NativeLibraryLoader {

    private static Logger logger = LogManager.getLogger();

    /**
     * This is a safe way to load a native library from a jar, assuming that library
     * is inside your resource director/classpath.
     */
    public static void loadLibraryFromJar(String libraryName) throws IOException {
        logger.debug("Loading native library %s".formatted(libraryName));
        InputStream is = NativeLibraryLoader.class.getResourceAsStream("/" + libraryName);
        File library = File.createTempFile("jni-temp-file", "tmp");
        library.deleteOnExit();
        try (OutputStream os = new FileOutputStream(library)) {
            logger.debug("Copying library input stream to temp file " + library.getPath());
            os.write(is.readAllBytes());
        }
        logger.debug("Loading library " + library.getPath());
        System.load(library.getPath().replace("\\", "/"));
    }

}

报错信息 #

[ERROR] Tests run: 2, Failures: 0, Errors: 2, Skipped: 0, Time elapsed: 0.188 s <<< FAILURE! - in com.toughdata.autogrowth.TestOpenCVCaptchaProcessor
[ERROR] testSolveRotateCaptchaIsKnownValue  Time elapsed: 0.187 s  <<< ERROR!
java.lang.UnsatisfiedLinkError: C:\Users\greg\AppData\Local\Temp\jni-temp-file78576686543799615tmp: Can't find dependent libraries
        at com.toughdata.autogrowth.TestOpenCVCaptchaProcessor.testSolveRotateCaptchaIsKnownValue(TestOpenCVCaptchaProcessor.java:16)

[ERROR] testSolvePuzzleCaptchaIsKnownValue  Time elapsed: 0 s  <<< ERROR!
java.lang.NoClassDefFoundError: Could not initialize class com.toughdata.autogrowth.automation.captcha.OpenCVCaptchaProcessor
        at com.toughdata.autogrowth.TestOpenCVCaptchaProcessor.testSolvePuzzleCaptchaIsKnownValue(TestOpenCVCaptchaProcessor.java:24)
Caused by: java.lang.ExceptionInInitializerError: Exception java.lang.UnsatisfiedLinkError: C:\Users\greg\AppData\Local\Temp\jni-temp-file78576686543799615tmp: Can't find dependent libraries [in thread "main"]
        at com.toughdata.autogrowth.TestOpenCVCaptchaProcessor.testSolveRotateCaptchaIsKnownValue(TestOpenCVCaptchaProcessor.java:16)

核心原因：Windows与Linux的Native库加载机制差异 #

1. 依赖查找路径不同
   • Linux下，.so文件的依赖查找会优先使用编译时嵌入的rpath（OpenCV编译时通常会设置），同时系统默认库路径也会被扫描，因此仅加载主库即可自动找到依赖。
   • Windows下，DLL加载器只会在当前工作目录、系统目录、PATH环境变量包含的路径中查找依赖DLL。临时目录不在这些路径里，且OpenCV的opencv_490.dll依赖其他组件（如opencv_core490.dll、opencv_imgproc490.dll），这些依赖未被加载也无法被找到。
2. 临时文件命名问题
   使用File.createTempFile生成的文件后缀是.tmp，而非原DLL文件名（如opencv_490.dll）。OpenCV的DLL之间是通过文件名互相引用的，改名后无法识别依赖关系。

解决方案 #

1. 打包所有OpenCV依赖DLL #

确保Jar包中包含Windows版本OpenCV的所有必要DLL，包括核心组件（如opencv_core490.dll、opencv_imgproc490.dll）以及VC运行库（如vcruntime140.dll、msvcp140.dll，若OpenCV使用VC编译）。

2. 修改加载逻辑：保留原文件名+统一临时目录+添加PATH #

修改NativeLibraryLoader，将所有依赖DLL提取到同一个临时目录，保留原文件名，并将临时目录加入系统PATH，让Windows加载器能找到依赖。

修改后的代码示例：

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import java.io.*;
import java.nio.file.Files;
import java.nio.file.Path;

public class NativeLibraryLoader {

    private static Logger logger = LogManager.getLogger();
    private static Path tempDir;

    static {
        try {
            // 创建专属临时目录
            tempDir = Files.createTempDirectory("opencv-native-libs");
            tempDir.toFile().deleteOnExit();
            // 将临时目录添加到PATH开头
            String currentPath = System.getenv("PATH");
            String newPath = tempDir.toString() + File.pathSeparator + currentPath;
            System.setenv("PATH", newPath);
            // 刷新JVM的库路径
            try {
                ClassLoader loader = ClassLoader.getSystemClassLoader();
                java.lang.reflect.Field field = ClassLoader.class.getDeclaredField("usr_paths");
                field.setAccessible(true);
                String[] paths = (String[]) field.get(loader);
                String[] newPaths = new String[paths.length + 1];
                newPaths[0] = tempDir.toString();
                System.arraycopy(paths, 0, newPaths, 1, paths.length);
                field.set(loader, newPaths);
            } catch (Exception e) {
                logger.warn("Failed to refresh library path, relying on PATH environment variable", e);
            }
        } catch (IOException e) {
            logger.error("Failed to create temporary directory for native libraries", e);
            throw new RuntimeException(e);
        }
    }

    public static void loadLibraryFromJar(String libraryName) throws IOException {
        logger.debug("Loading native library: {}", libraryName);
        InputStream is = NativeLibraryLoader.class.getResourceAsStream("/" + libraryName);
        if (is == null) {
            throw new FileNotFoundException("Native library not found in classpath: " + libraryName);
        }
        // 保留原文件名写入临时目录
        Path libraryPath = tempDir.resolve(libraryName);
        File libraryFile = libraryPath.toFile();
        libraryFile.deleteOnExit();

        try (OutputStream os = new FileOutputStream(libraryFile)) {
            logger.debug("Copying library to temp file: {}", libraryFile.getAbsolutePath());
            byte[] buffer = new byte[4096];
            int bytesRead;
            while ((bytesRead = is.read(buffer)) != -1) {
                os.write(buffer, 0, bytesRead);
            }
        }

        logger.debug("Loading library: {}", libraryFile.getAbsolutePath());
        System.load(libraryFile.getAbsolutePath());
    }

    // 批量加载多个依赖库
    public static void loadLibrariesFromJar(String... libraryNames) throws IOException {
        for (String libName : libraryNames) {
            loadLibraryFromJar(libName);
        }
    }
}

3. 使用方式 #

按依赖顺序加载所有必要DLL：

NativeLibraryLoader.loadLibrariesFromJar(
    "opencv_core490.dll",
    "opencv_imgproc490.dll",
    "opencv_490.dll"
);

关键修改点说明 #

• 统一临时目录：所有DLL提取到同一目录，保证依赖库与主库在同一位置。
• 保留原文件名：确保OpenCV的DLL能通过正确文件名找到彼此。
• 修改PATH环境变量：让Windows加载器扫描到临时目录中的依赖DLL。
• 批量加载：按依赖顺序加载所有必要DLL，避免加载顺序错误。

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