Jenkins构建失败？用项目内仓库管理第三方私有JAR包

先说一个我经常遇到的场景：本地IDEA里编译、测试、跑Spring Boot全都正常，代码一推到Git，Jenkins上的构建任务立刻变红，控制台刷出“Failure to find com.example:private-sdk:jar:1.2.0 in ...”或“package com.private.sdk does not exist”。这种Jenkins构建问题，十有八九不是代码写得有问题，而是项目依赖了一个第三方私有JAR包，而这个JAR只躺在某个人的电脑里，或者只在某个同事本地安装过。

所谓第三方私有JAR包，简单说就是无法从Maven中央仓库下载的JAR。可能是供应商给你的收费SDK，可能是公司老系统里抽出来又没开源的工具类，也可能是某个曾经在本地Maven仓库里被手动安装过的历史遗留包。本来直接在pom.xml里写一个dependency，Maven就会自动从中央仓库拉取。可一旦坐标对应的是私有JAR，干净环境下的Jenkins就再也找不到了。

解决这类问题有个非常直接的办法：把这个第三方私有JAR包存入项目里，让依赖跟着代码走。具体可以做成lib目录配systemPath，也可以做成本地file://仓库。今天这篇就围绕这个思路展开，把方案对比、实操步骤、Jenkins配置和踩坑经验一起梳理一遍。如果你正在被Jenkins打包失败折磨，或者刚接触Maven私有依赖管理，这篇应该能帮上忙。

1. 为什么Jenkins构建会卡在第三方私有JAR包上

1.1 报错现场：本地能编译，Jenkins却飘红

先还原一下报错画面。代码仓库里的DemoApplication.java有一行import com.private.sdk.PrivateClient;，本地Maven编译一点问题都没有，但Jenkins控制台输出的内容基本长这样：

code复制[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.8.1:compile (default-compile) on project demo: Compilation failure
[ERROR] /var/lib/jenkins/workspace/demo/src/main/java/com/example/DemoApplication.java:[12,24] package com.private.sdk does not exist
[ERROR] /var/lib/jenkins/workspace/demo/src/main/java/com/example/DemoApplication.java:[13,28] cannot find symbol
[ERROR]   symbol:   class PrivateClient

如果你只声明了依赖坐标，还没有把JAR放进来，报错可能会更直接：

code复制[ERROR] The project com.example:demo:1.0.0 (/workspace/pom.xml) has 1 error
[ERROR] 'dependencies.dependency.version' for com.private:sdk:jar is missing.

为什么会这样？本地开发时，IDE通常会把工作区里的类库、历史下载过的依赖都记在本地，甚至有的同事直接在IDE里“手动加了一个jar包”，这在本地完全没影响。但Jenkins每次构建都是从一个干净的workspace开始，它会严格按照pom.xml里声明的依赖去解析，不会因为你某个同事的电脑上“有这个jar”就认为它能用。于是Maven开始到处找：

• 先看~/.m2/repository本地仓库里有没有；
• 再看settings.xml里配置的镜像私服里有没有；
• 最后去看中央仓库；
• 如果都没有，直接报错，构建失败。

对于第三方私有JAR，这三条路基本都走不通。本地仓库没有，公司又没有私服，中央仓库更不可能收录一个商业闭源的SDK。所以这个问题的本质不是Jenkins配置错了，而是依赖管理上游缺了一环。

1.2 私有JAR包的常见来源

我在实际项目里遇到的私有JAR包，大致能分成三类：

• 商业SDK：比如某个硬件厂商提供的读卡器驱动、某个支付渠道的加签SDK、某个地图商的定位组件。这些JAR通常直接发给你一个压缩包，里面连源码和文档一起打包，但绝不会出现在Maven中央仓库里。
• 公司内部公共组件：老项目里抽出来的工具类、协议解析包、数据访问组件，代码在公司内部流传，但一直没人把它发布到公司的Nexus或者其他制品库。
• 第三方技术人员现场给的JAR：比如外包团队交接时丢给你一个编译好的包，口头说“你们自己放在项目里引用就行”，后续就没有任何维护了。

这三种情况有一个共同点：它们都是“真实存在于同事电脑或项目目录里，但不存在于标准制品仓库”的依赖。只要你的构建环境脱离了某台特定的电脑，就会立刻出问题。

1.3 核心思路：让JAR跟着代码走

既然问题出在“依赖不在标准仓库”，最简单的处理就是不要指望从网上拉取，直接把JAR塞进项目代码仓库。这么做有几个明显的好处：

• 环境无关：Jenkins每次从Git拉代码，JAR和pom.xml一起出现，不用在构建机上做任何“人肉准备”。
• 协作简单：新同事clone项目后能直接构建，不用在群里问“那个SDK谁能发我一份”。
• 变更可回溯：JAR的升级、替换都会体现在代码提交记录里，出问题知道是谁在什么时候改的。

当然，把JAR提交进项目不是没有代价，后面会再讲体积和维护问题。但相对一个稳定可复现的构建流程，这个代价通常在可接受范围内。

2. 方案对比：私服、本地仓库、项目内入库怎么选

2.1 三种主流方案横向对比

在处理第三方私有JAR时，我见过大家用最多的其实是三种方案。

很多同学一开始会选第二个方案，因为只需要执行一条命令：

bash复制mvn install:install-file -Dfile=lib/private-demo-sdk-1.2.0.jar -DgroupId=com.example -DartifactId=private-demo-sdk -Dversion=1.2.0 -Dpackaging=jar

执行完之后，JAR被安装到了当前机器的~/.m2/repository下，pom.xml里只要写普通的dependency坐标就能编译。这种方案确实很省事，但它的致命伤在于“这个JAR只存在于这一台机器的本地仓库”。假如你的Jenkins只有一个执行机且永远不换，短期可能没问题；但只要那天管理员清理了~/.m2，或者Jenkins改用多个节点跑任务，原本能过的构建就会再次翻车。持续集成最怕的就是“环境有状态”，依赖的解析不能靠某台机器上恰好装了什么东西。

2.2 项目内入库的两个分支

确定走“把JAR存入项目”这条路之后，还要再细分一下怎么让Maven识别项目里的JAR。这里有两个分支：

• system scope + systemPath：在pom.xml里把一个依赖的scope设成system，并用systemPath指到项目路径下的JAR文件。Maven看到后不再去仓库解析坐标，直接用本地文件。
• project-local file repository：在项目根目录放一个符合Maven标准仓库结构的目录，比如repo/，然后在pom.xml的<repositories>里加一个file://地址，让Maven把这个目录当成一个“本地远程仓库”来解析依赖。

这两个分支各有适用场景。第二分支兼容性更好，我通常更推荐；但第一分支在某些快速验证场景下也很方便。下面具体看操作。

3. 实操教程：把第三方私有JAR包存进项目仓库

3.1 第一步：创建lib目录并整理JAR

先别急着改pom.xml，第一步是确定好项目里放置私有JAR的位置。最常见的做法是在项目根目录创建一个lib/目录，或者叫libs/，看团队习惯。

目录结构大致如下：

code复制your-project/
├── lib/
│   └── private-demo-sdk-1.2.0.jar
├── src/
│   └── main/
│       ├── java/
│       └── resources/
└── pom.xml

JAR文件命名建议遵循{artifactId}-{version}.jar，比如private-demo-sdk-1.2.0.jar。这样做的好处是在依赖坐标和文件名之间能一眼对应起来，排查问题时不至于满目录找。如果JAR还附带LICENSE、README、接口文档，建议一并放进去，命名上做好区分，比如private-demo-sdk-1.2.0-README.txt。

这里有一个容易踩的坑：很多团队的.gitignore会写*.jar，用来屏蔽编译产物的。如果你把私有JAR放在lib目录下，这个规则会把JAR也排除掉，导致提交到Git后别人拉下来根本没有文件。所以一定要确认.gitignore不会误伤lib目录，或者给lib目录加例外规则。建议在.gitignore里显式写：

code复制*.jar
!lib/*.jar

3.2 方式一：system scope + systemPath（最快，但有隐患）

如果你只有一两个私有JAR，而且项目不是特别复杂的多模块结构，用system scope是最快的。

在pom.xml里添加依赖：

xml复制<dependency>
    <groupId>com.example</groupId>
    <artifactId>private-demo-sdk</artifactId>
    <version>1.2.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/private-demo-sdk-1.2.0.jar</systemPath>
</dependency>

这里有几个要点：

• groupId、artifactId、version可以自己拟定，但一定要和JAR实际来源对应上，不要随手写个aa：bb：1.0，否则后续维护会非常痛苦。
• systemPath必须用${project.basedir}开头，不要直接写/home/user/...这种绝对路径。否则别人拉下代码，路径对不上，构建一定失败。
• scope=system意味着这个依赖不会参与传递，不会被打进正常的Maven依赖树，后续如果有其他模块直接引用这个JAR里的类，会找不到依赖。

比较麻烦的是Spring Boot场景。如果项目用了spring-boot-maven-plugin，默认情况下system范围的依赖不会被打进最终的可执行JAR。你需要额外配置：

xml复制<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <includeSystemScope>true</includeSystemScope>
    </configuration>
</plugin>

不配置的话，本地IDE运行可能正常，因为IDE通常会把所有依赖都加到classpath里；但Jenkins打出来的jar丢到服务器上运行，就会报NoClassDefFoundError。这个问题后面在“常见问题”里还会再讲。

3.3 方式二：项目内file仓库（更稳，我更推荐）

如果你希望依赖能被Maven正常解析、传递，并且打包时不搞特殊处理，我推荐用“项目内file仓库”。

具体分四步走。

第一步：在项目根目录创建repo/目录，并按照Maven仓库的目录结构放置JAR文件。Maven仓库的路径规则是groupId的包名路径/artifactId/version/，比如：

code复制repo/
└── com/
    └── example/
        └── private-demo-sdk/
            └── 1.2.0/
                ├── private-demo-sdk-1.2.0.jar
                └── private-demo-sdk-1.2.0.pom

注意这里的com/example对应groupId里的com.example，目录层级是按点号拆开拼成的路径。

第二步：写一个最简pom文件放在同目录下。如果JAR本身没有附带pom，你可以手工建一个，内容不复杂：

xml复制<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>private-demo-sdk</artifactId>
    <version>1.2.0</version>
</project>

这个pom存在的意义是让Maven在解析坐标时能有完整的元数据。没有它，某些场景下Maven虽然也能识别JAR，但遇到依赖传递时会报错。

第三步：在项目的pom.xml里增加一个repository，指向这个目录：

xml复制<repositories>
    <repository>
        <id>project-local</id>
        <url>file://${project.basedir}/repo</url>
    </repository>
</repositories>

第四步：在dependencies里正常声明依赖，不需要再写systemPath：

xml复制<dependency>
    <groupId>com.example</groupId>
    <artifactId>private-demo-sdk</artifactId>
    <version>1.2.0</version>
</dependency>

这样配置完之后，Maven会把${project.basedir}/repo目录当成一个“远程仓库”来读取依赖。因为地址是file://，所以实际上没有网络请求，只是从本地文件系统读取。但这个路径是标准的仓库布局，所以Maven的各种解析逻辑、依赖传递、插件打包都能正常工作。

我在实际项目里，只要不是那种临时验证用的demo，基本都会用这种file仓库方式。它没有system scope那些奇异行为，构建产物和普通依赖完全一致。

3.4 补充：把“安装私有JAR”的命令也放进项目里

还有一种变通做法，就是把JAR当作普通坐标依赖写进pom，但在构建前先执行一条install:install-file命令，把项目里的JAR安装到构建机的本地Maven仓库。

为了不让这个命令失传，我建议在项目根目录放一个脚本，比如scripts/install-private-jar.sh：

bash复制#!/bin/bash
mvn install:install-file \
  -Dfile=lib/private-demo-sdk-1.2.0.jar \
  -DgroupId=com.example \
  -DartifactId=private-demo-sdk \
  -Dversion=1.2.0 \
  -Dpackaging=jar

然后在Jenkins流水线里，构建之前先执行这个脚本。这样pom.xml里依赖就是普通的compile scope，不涉及systemPath，也不涉及file://仓库路径问题。JAR文件仍然存放在项目里，环境不同时也能用脚本重新装到任何一台机器。

这种方案的缺点是：多节点Jenkins下每个节点都要执行一次脚本，而且本地仓库会有状态。但相比直接手敲命令，它至少把“怎么安装”这件事固化在项目里了，不会因为换人接手就失传。

3.5 两种项目内方案怎么选

我把systemPath和file仓库放在一起对比。

所以我的默认选择是file仓库。除非项目只有一个简单模块，并且没有复杂的打包需求，否则不要为了少写几行配置去碰systemPath。

4. 结合Jenkins：构建稳定通过的关键配置

4.1 为什么项目内JAR方案对CI最友好

Jenkins的核心职责是“从代码开始构建出可交付物”，而不是依赖某台机器上预先装好的东西。项目内JAR方案正好契合这一点。每次构建，Jenkins都会从Git仓库拉取最新代码，lib/或repo/目录会跟着代码一起出现，不需要额外去某个共享目录拷贝，也不需要先登录Nexus下载依赖。

所以从CI视角看，这个方案的故障面最小。你不需要担心Jenkins机器上没装Nexus证书、私服账号过期、私有依赖被不小心删掉等等。只要是写在代码仓库里的东西，就会天然地出现在每一次构建中。

4.2 Jenkins构建命令与Pipeline示例

构建命令不用做什么特殊处理。普通Maven项目依然用：

bash复制mvn clean package -DskipTests

如果需要把模块安装到本地仓库，供后续或者多模块使用，就用mvn clean install。只要pom.xml里配置正确，clean package就会默认把项目里的私有依赖解析进来。

一个简单的Jenkins Pipeline大概长这样：

groovy复制pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package -DskipTests'
            }
        }
        stage('Archive') {
            steps {
                archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
            }
        }
    }
}

如果用的是3.3节的file仓库方式，这个Pipeline不需要额外步骤，直接跑就能过。如果用的是3.2节的systemPath，并且是Spring Boot项目，记得先确认pom里是否已经配置了includeSystemScope，否则会出现构建成功但运行时报错的诡异局面。

4.3 多模块项目里的路径问题

多模块项目是file仓库方式最容易埋雷的地方。原因很简单：${project.basedir}在父模块和子模块中解析出来的路径不一样。

假设你有一个父工程parent，下面有子模块module-a、module-b。如果把repo目录放在父工程根目录，并在父pom的<repositories>里写file://${project.basedir}/repo，那么在父pom解析时这个路径是parent/repo，没问题。但子模块继承这个配置后，${project.basedir}可能会被当成子模块的目录来解析，结果子模块去找parent/module-a/repo，自然找不到。

遇到这种情况，我一般有两种处理方式：

• 在每个需要私有依赖的子模块里，各自配置repository的url，路径按模块到根目录的层级去写，比如file://${project.basedir}/../repo，如果模块更深，就../../repo。
• 抛弃file仓库，改用脚本方式：在Jenkins Pipeline里先执行3.4节的install-private-jar.sh，然后pom里使用普通坐标依赖。这样完全绕开file URL路径解析的坑。

我个人的经验是，多模块项目里更稳的是第二种方式。因为多模块本身就是一件需要统一构建顺序的事情，没必要再让每个子模块去猜repo路径。

4.4 在Pipeline中先安装私有JAR再构建

这里给出一个完整可用的Pipeline片段：

groovy复制pipeline {
    agent any
    stages {
        stage('Install private jar') {
            steps {
                sh '''
                    mvn install:install-file \
                      -Dfile=lib/private-demo-sdk-1.2.0.jar \
                      -DgroupId=com.example \
                      -DartifactId=private-demo-sdk \
                      -Dversion=1.2.0 \
                      -Dpackaging=jar
                '''
            }
        }
        stage('Maven package') {
            steps {
                sh 'mvn clean package -DskipTests'
            }
        }
    }
}

在这个方案里，pom.xml只需要声明普通依赖，不需要systemPath，也不需要file://仓库。JAR文件静静地躺在lib/目录里随代码走，构建时先把它装进本地仓库，Maven自然能解析到。

这种组合的好处是：pom干净、多模块友好、打包行为正常。代价是Jenkins执行机的~/.m2会被写入一个私有JAR，但只要每次构建都执行install命令，就不会有“旧版本残留”的问题。如果你用的是多节点Jenkins，确保Pipeline里的install stage在所有节点都能跑到就行。

5. 常见问题排查：打包失败、运行报错和版本管理

5.1 典型错误速查表

我把实际遇到过的问题整理成了一张速查表，供参考。

这些报错里，前两条在“寻找JAR”阶段就会暴露，比较容易定位。真正隐蔽的是第三种，构建阶段完全正常，等到运行时才炸，这时候排查路径就比较长了。

5.2 我踩过的一个坑：Jenkins构建成功，跑到线上却NoClassDefFoundError

有次接一个支付SDK，我图省事，在pom里用了systemPath方式配好，本地IDEA启动完全正常。Jenkins构建也显示成功，生成的可执行JAR大小看起来也没问题。结果一部署到测试环境，进程启动时直接抛NoClassDefFoundError：

code复制Exception in thread "main" java.lang.NoClassDefFoundError: com/private/sdk/PrivateClient

当时第一反应是打包没打全，于是我打开Jenkins构建出来的jar，用命令检查内部结构：

bash复制jar tf target/app.jar | grep private-demo

结果发现BOOT-INF/lib下面根本没有那个JAR。原因是Spring Boot的repackage插件默认不把scope=system的依赖打进fat jar，虽然编译时能用，但运行时不打包进去。

后来我改成项目内file仓库方式，重新构建，再执行一次jar tf，能看到JAR出现在BOOT-INF/lib/private-demo-sdk-1.2.0.jar，问题立刻消失。这个坑让我对systemPath有了心理阴影。从那以后，但凡遇到这种“第三方私有JAR”需求，我第一反应都是建议用file仓库或者install-file脚本方式，而不是在pom里写systemPath。

5.3 私有JAR升级与版本一致性

私有JAR最常见的管理问题就是版本混乱。有人直接把新版本的jar覆盖了旧版本文件，然后commit上去，JAR文件名和版本号完全对不上。这种隐蔽问题最容易让后来的人一头雾水。

我的建议是：

• 固定版本号，不要用SNAPSHOT版本做私有依赖。
• 升级时保留旧版本文件，比如把1.1.0.jar和1.2.0.jar都放在lib目录或repo目录下，pom里显式引用某个版本。
• 在pom.xml里给私有依赖加注释，标明JAR来源、获取日期、联系人。别小看这几行注释，半年后能省很多沟通成本。

如果使用file仓库方式，升级时记得同步更新repo/目录下的pom文件版本号和jar文件名，避免Maven解析到错误的坐标元数据。

6. 项目内JAR仓库的维护与团队协作建议

6.