一、背景说明

日常开发中，我们的Java项目常会引用公司私有Maven仓库中的第三方私有JAR包。但在部署Jenkins构建环境时，由于网络限制，Jenkins服务器无法访问公司内部的私有Maven私服，导致依赖下载失败、构建报错。

针对该问题，最直接有效的解决方案是：将需要的私有JAR包直接存入项目目录中，通过Maven配置引用本地JAR包，摆脱对私有私服的依赖，确保Jenkins正常构建。

二、技术原理

核心利用Maven的system依赖作用域，直接引用项目本地目录中的JAR包，替代从远程私服下载依赖；同时配置Spring Boot打包插件，确保本地私有JAR包能被正常打入最终构建产物（JAR/WAR包），保证项目部署后可正常运行。

三、详细实现步骤（附代码示例）

步骤1：从私有Maven私服下载JAR包到本地

首先需要将公司私有Maven私服中所需的JAR包，下载到本地开发环境的Maven仓库中，执行以下Maven命令即可（需替换为实际的groupId、artifactId和version）：

mvn dependency:get -DgroupId=com.itl -DartifactId=itl-sso-core -Dversion=1.3.0-SNAPSHOT

执行成功后，JAR包会自动下载到本地Maven仓库（默认路径：~/.m2/repository），后续我们只需从该路径复制JAR包即可。

步骤2：在项目中创建Lib目录并放入私有JAR包

1. 打开你的Java项目（与pom.xml文件同级），新建一个名为lib的文件夹（用于专门存放本地私有JAR包，规范项目结构）；

2. 从本地Maven仓库中，找到步骤1下载的私有JAR包（示例：microservice-common-1.0.0-SNAPSHOT.jar），复制到项目根目录的lib文件夹中。

⚠️ 注意：确保JAR包名称与后续配置中的路径一致，避免因名称错误导致引用失败。

步骤3：修改pom.xml，引用本地Lib目录的JAR包
将pom.xml文件中，原有对私有私服JAR包的依赖配置，替换为本地路径引用，核心配置如下（直接复制替换，修改对应参数即可）：

<dependencies>
<!-- 引用本地lib目录下的私有JAR包 -->
    <dependency>
        <groupId>com.itl</groupId>  <!-- 与私有JAR包的groupId一致 -->
        <artifactId>itl-oss-core</artifactId> <!-- 与私有JAR包的artifactId一致 -->
        <version>1.3.0-SNAPSHOT</version>  <!-- 与私有JAR包的版本一致 -->
        <scope>system</scope> <!-- 固定为system，标识引用本地系统文件 -->
        <systemPath>${project.basedir}/lib/microservice-common-1.0.0-SNAPSHOT.jar</systemPath> 
        <!-- 本地JAR包相对路径 -->
    </dependency>
    <!-- 其他项目依赖... -->
</dependencies>

说明：${project.basedir}是Maven内置变量，代表项目根目录，无需手动修改，确保路径适配不同环境。

步骤4：替换Maven仓库地址为阿里云公共仓库
由于Jenkins无法访问公司私有私服，需将pom.xml中的Maven仓库地址，替换为阿里云公共仓库，确保其他公共依赖（如Spring Boot相关依赖）能正常下载。

<repositories>
    <repository>
        <id>aliyunmaven</id>
        <name>阿里云中央仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

    <pluginRepositories>
    <!-- 插件仓库也同步替换为阿里云，确保Maven插件正常下载 -->
    <pluginRepository>
        <id>aliyunmaven</id>
        <name>阿里云插件仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

配置完成后，建议清理本地Maven仓库中该私有JAR包的缓存（删除~/.m2/repository/com/microservice/microservice-common目录），避免Maven优先读取本地私服缓存，导致配置不生效。

步骤5：配置Spring Boot打包插件（关键步骤）

如果是Spring Boot项目，默认情况下，system作用域的JAR包不会被打入最终的构建产物中，因此必须修改spring-boot-maven-plugin插件配置，添加includeSystemScope=true，确保本地私有JAR包被正常打包。

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
               <!-- 核心配置：包含system作用域的依赖，确保私有JAR包被打入构建产物 -->
                <includeSystemScope>true</includeSystemScope>
            </configuration>
        </plugin>
        <!-- 其他插件配置... -->
    </plugins>
</build>

步骤6：执行打包命令，验证配置生效

进入项目根目录（包含pom.xml文件的目录），执行以下Maven打包命令，跳过测试类编译，加快打包速度：

mvn clean package -Dmaven.test.skip=true -U

✅ 验证标准：

• 命令执行无报错，控制台输出BUILD SUCCESS；

• 项目target目录下生成最终的JAR包，通过jar tf target/你的项目名.jar命令查看，能找到私有JAR包对应的包路径（如com/microservice/common/…），说明打包成功。

四、常见问题与注意事项

1. 路径错误导致引用失败：确保systemPath中的路径正确，${project.basedir}无需修改，JAR包名称与配置完全一致（区分大小写）；

2. 多模块项目适配：若为Maven多模块项目，建议将lib目录放在父模块根目录，子模块引用时路径改为${project.parent.basedir}/lib/xxx.jar；

3. 版本一致性：本地lib目录的JAR包版本，必须与pom.xml中配置的version一致，避免版本冲突；

4. Jenkins环境适配：将修改后的项目代码提交到Git仓库，Jenkins拉取代码后，无需额外配置，执行上述打包命令即可正常构建（确保Jenkins服务器能访问阿里云仓库）。

五、总结

本文核心解决“网络限制下，Jenkins无法访问私有Maven私服”的构建问题，通过“本地下载JAR包 → 项目内存储 → Maven配置本地引用 → 打包插件适配”四个核心步骤，实现私有JAR包的本地化管理，摆脱对私有私服的依赖。

该方案操作简单、适配性强，不仅适用于Jenkins构建，也适用于其他无法访问私有私服的离线开发/部署场景，可直接照搬步骤应用到实际项目中。

如果觉得本文有用，欢迎点赞+收藏，有疑问可在评论区留言交流~