将GraalPy打包进Spring Boot Jar后出现模块找不到问题

核心结论 #

完全可以将包含第三方库的Python虚拟环境打包进Spring Boot FatJar，但你的配置存在路径识别问题——GraalPy无法处理Jar内的虚拟环境可执行文件路径，需要调整上下文配置和打包规则。

问题原因 #

你通过getResource().getPath()获取的Jar内路径（格式类似file:/xxx.jar!/BOOT-INF/classes!/venv/bin/graalpy）是Jar资源的URL格式，并非文件系统上的真实可执行文件路径。GraalPy无法通过这个路径加载虚拟环境，自然找不到pystac模块，尽管它已经被打包进Jar。

解决方案 #

1. 调整GraalPy上下文配置，直接指定第三方库路径 #

移除无效的python.Executable配置，改用python.Path直接指定Jar内的site-packages路径，让GraalPy直接加载第三方模块：

// 获取site-packages目录的资源URL
URL sitePackagesUrl = ConfigService.class.getClassLoader()
        .getResource("venv/lib/python3.8/site-packages");

// 处理Jar内路径和本地开发路径的差异
String sitePackagesPath;
if ("jar".equals(sitePackagesUrl.getProtocol())) {
    // Jar环境下使用完整的Jar资源URL格式
    sitePackagesPath = sitePackagesUrl.toString();
} else {
    // 开发环境使用文件系统路径
    sitePackagesPath = sitePackagesUrl.getPath();
}

// 创建GraalPy上下文
var context = Context.newBuilder("python")
        .allowAllAccess(true)
        .option("python.Path", sitePackagesPath) // 直接添加模块搜索路径
        .option("python.ForceImportSite", "true")
        .build();

2. 确保Maven正确打包Python虚拟环境 #

在pom.xml中添加资源配置，保证venv目录下的所有文件都被打包进FatJar的BOOT-INF/classes目录：

<build>
    <resources>
        <!-- 默认资源目录 -->
        <resource>
            <directory>src/main/resources</directory>
        </resource>
        <!-- 打包Python虚拟环境 -->
        <resource>
            <directory>venv</directory>
            <includes>
                <include>**/*</include>
            </includes>
        </resource>
    </resources>
</build>

如果你的虚拟环境不在项目根目录，需要修改directory路径为实际的venv位置。

3. 移除python.Executable配置 #

GraalVM已经内置了GraalPy运行时，不需要指定Jar内的可执行文件——它不是文件系统上的可执行程序，无法被GraalPy调用。

验证步骤 #

1. 重新执行mvn clean package构建FatJar
2. 运行Jar包，检查ModuleNotFoundError是否消失
3. 如果仍有问题，解压Jar包确认BOOT-INF/classes/venv/lib/python3.8/site-packages/pystac目录存在

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