You need to enable JavaScript to run this app. 如何解决可执行胖Jar使用本地Jar库时的类找不到报错问题
优惠活动
大模型
产品
解决方案
定价
更多

如何解决可执行胖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。执行安装命令即可:
      mvn install:install-file -Dfile=你的本地Jar物理路径/xxx.jar -DgroupId=自定义分组名 -DartifactId=自定义组件名 -Dversion=自定义版本号 -Dpackaging=jar
      
      安装完成后按照普通依赖格式引入即可,这种方式兼容性最好,不会在CI环境、Docker构建时因为本地路径不存在出问题。
    • 临时方案:如果不想把本地Jar装入仓库,用Spring Boot官方插件打包时,需要额外开启system范围依赖的打包开关,在spring-boot-maven-plugin的配置里加上:
      <configuration>
          <includeSystemScope>true</includeSystemScope>
      </configuration>
      

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.13 08:18:09