如何解决可执行胖Jar使用本地Jar库时的类找不到报错问题
这类问题的核心排查方向
本质原因都是打出来的可执行胖Jar没有把你引入的本地Jar包含进去,或者Jar内的存放结构不符合Spring Boot类加载规则——毕竟mvn spring-boot:run能正常跑,说明Maven编译、运行时的类路径是能找到这个类的,问题全出在打包环节。
按照踩坑概率从高到低梳理解决步骤:
1. 优先检查本地Jar的依赖配置
这是最高发的踩坑点:
- 如果你引入本地Jar的时候用了
<scope>system</scope>直接关联本地文件路径,不管是Assembly插件还是Spring Boot官方打包插件,默认都不会把这部分system范围的依赖打进最终Jar包,运行时自然抛出类找不到的错误。 - 两种处理方式按需选择:
- 推荐方案:把本地Jar安装到本地Maven仓库,用标准GAV坐标引入,完全去掉system scope。执行安装命令即可:
安装完成后按照普通依赖格式引入即可,这种方式兼容性最好,不会在CI环境、Docker构建时因为本地路径不存在出问题。mvn install:install-file -Dfile=你的本地Jar物理路径/xxx.jar -DgroupId=自定义分组名 -DartifactId=自定义组件名 -Dversion=自定义版本号 -Dpackaging=jar - 临时方案:如果不想把本地Jar装入仓库,用Spring Boot官方插件打包时,需要额外开启system范围依赖的打包开关,在
spring-boot-maven-plugin的配置里加上:<configuration> <includeSystemScope>true</includeSystemScope> </configuration>
- 推荐方案:把本地Jar安装到本地Maven仓库,用标准GAV坐标引入,完全去掉system scope。执行安装命令即可:
2. 核对打包插件的配置合理性
你第一版用Assembly插件打包装配正常,但是引入本地Jar后出问题,要重点核对两处配置:
- 检查
assembly.xml里的<dependencySets>规则:有没有把所有runtime、compile范围的依赖都扫描到,有没有误把本地Jar对应的依赖排除;同时要确认Jar内的结构完全符合Spring Boot可执行Jar的要求:自己编写的业务类要放在BOOT-INF/classes路径下,所有依赖Jar要放在BOOT-INF/lib路径下——只要存放路径不对,哪怕Jar文件被打进去了,Spring Boot的自定义类加载器也读不到。 - 长期建议放弃手撸Assembly配置打Spring Boot可执行Jar,直接用Spring Boot官方提供的
spring-boot-maven-plugin的repackage目标,只要依赖能被Maven正常解析,插件会自动按照标准结构打包,从根源避免路径错配的问题。
3. 打完包先做基础验证,避免无效调整
每次改完配置打完Jar,先执行下面的命令确认本地Jar有没有被正确打进包内,不要上来就瞎调整配置:
# 查看Jar包内的文件列表,搜索你引入的本地Jar文件名 jar tf 打出来的可执行Jar.jar | grep 本地Jar的文件名
- 如果搜不到对应的Jar,说明是依赖配置或者打包插件的扫描规则没覆盖到,回头核对上面两步的配置即可。
- 如果能搜到对应的Jar,那就是Jar内存放的路径不符合Spring Boot类加载规则,调整打包结构到标准路径就行。
内容的提问来源于stack exchange,提问作者touati
相关产品推荐
相关产品推荐

