如何在 Jenkins 中正确构建含本地 JAR 依赖的 Maven 项目-java教程-PHP中文网

本文详解 Jenkins 构建失败的根本原因（本地 JAR 路径不可达、system 依赖未打包、资源复制路径错误），并提供可落地的三步解决方案：统一存放 lib/、修正 maven-resources-plugin 配置、启用 spring-boot-maven-plugin 的 includeSystemScope，确保本地 JAR 稳定嵌入最终可执行包。

本文详解 jenkins 构建失败的根本原因（本地 jar 路径不可达、`system` 依赖未打包、资源复制路径错误），并提供可落地的三步解决方案：统一存放 `lib/`、修正 `maven-resources-plugin` 配置、启用 `spring-boot-maven-plugin` 的 `includesystemscope`，确保本地 jar 稳定嵌入最终可执行包。

Jenkins 构建失败的核心矛盾在于：本地开发环境与 CI 环境的路径语义不一致 + Maven 默认行为未覆盖 Spring Boot 打包逻辑。你本地 mvn clean package 成功，是因为开发机上 ruoyi-admin/lib/cesiumlanguagewriter-2.20.1.jar 确实存在，且 IDE 或命令行执行时工作目录（project.basedir）恰好指向模块根目录；而 Jenkins 使用 -f /var/lib/jenkins/workspace/qrd_back/pom.xml 指定父 POM 启动多模块构建，此时 ruoyi-admin 模块的 ${project.basedir} 实际解析为 /var/lib/jenkins/workspace/qrd_back/ruoyi-admin —— 若该路径下缺失 lib/ 目录或 JAR 文件，systemPath 即刻失效，后续 maven-resources-plugin 尝试复制 /BOOT-INF/lib/...jar 时因源文件不存在而报错 No such file or directory。

更关键的是，即使路径正确，Maven 默认不会将 scope=system 的依赖打入最终 JAR。Spring Boot 项目使用 spring-boot-maven-plugin 打包时，默认仅包含 compile 和 runtime 作用域的依赖，system 依赖被忽略。这就是为何本地能运行（IDE 类路径包含该 JAR），但 Jenkins 打出的 BOOT-INF/lib/ 中缺失该文件，导致运行时报 ClassNotFoundException。

✅ 正确解法需三步协同：

1. 确保 lib/ 目录严格纳入版本控制与 Jenkins 工作区

将 cesiumlanguagewriter-2.20.1.jar 放入 ruoyi-admin/lib/（而非父工程或其他路径），并在 .gitignore 中移除对该 JAR 的忽略规则，保证 Jenkins 拉取代码后 lib/cesiumlanguagewriter-2.20.1.jar 必然存在：

# 项目结构必须如下（Git 提交此目录）
ruoyi-admin/
├── pom.xml
├── lib/
│   └── cesiumlanguagewriter-2.20.1.jar  ← 必须被 Git 跟踪
└── src/

2. 修正 maven-resources-plugin 的配置

你当前配置中 lib 是相对路径，但 maven-resources-plugin 在多模块构建中可能因 basedir 解析偏差导致源路径错误。应显式使用 ${project.basedir} 并指定 filtering=false（JAR 不需过滤）：

Zyro AI Background Remover

Zyro推出的AI图片背景移除工具

下载

<build><resources><!-- ✅ 正确：明确指向模块级 lib 目录 --><resource><directory>${project.basedir}/lib</directory><targetpath>BOOT-INF/lib/</targetpath><includes><include>**/*.jar</include></includes><filtering>false</filtering><!-- 关键！避免 Maven 尝试解析 JAR 内容 --></resource><!-- 保留原有 resources（如 src/main/resources） --><resource><directory>${project.basedir}/src/main/resources</directory><targetpath>BOOT-INF/classes/</targetpath></resource></resources></build>

3. 强制 Spring Boot 插件打包 system 依赖

在 ruoyi-admin/pom.xml 的中，为 spring-boot-maven-plugin 添加 includeSystemScope=true：

<plugin><groupid>org.springframework.boot</groupid><artifactid>spring-boot-maven-plugin</artifactid><configuration><includesystemscope>true</includesystemscope><!-- ✅ 关键开关 --></configuration></plugin>

此配置确保插件将 system 作用域的 JAR 一并拷贝至 BOOT-INF/lib/，与 maven-resources-plugin 的复制行为形成双重保障。

⚠️ 重要提醒：

system 依赖是 Maven 的“临时方案”，不推荐用于生产级 CI/CD。长期应推动将私有 JAR 发布至 Nexus 私服，或通过 mvn install:install-file 统一安装到所有构建节点的本地仓库（需 Jenkins 共享 .m2 或配置 settings.xml）。
Jenkins 构建日志中 -X 输出显示 copy ... to /BOOT-INF/lib/...，说明路径拼接错误（缺少前导 target/classes/）。这印证了 maven-resources-plugin 的 targetPath 应为相对路径（如 BOOT-INF/lib/），而非绝对路径 /BOOT-INF/lib/ —— 删除开头的 / 即可。

完成上述调整后，Jenkins 构建将稳定通过，生成的 JAR 包内 BOOT-INF/lib/ 目录下必含 cesiumlanguagewriter-2.20.1.jar，彻底解决跨环境构建不一致问题。