Maven 项目构建打包，如何引入本地 Jar 包？

news2025/1/16 5:39:23

上一篇讲到 Maven 离线仓库的使用，反响不错很多人收藏，这一篇还是继续聊 Maven 。假如你发现某开源项目有个 bug 影响到自己的系统，但官方还没修复，自己定位到了本地修改打了包先应急用，那么如何在其他项目上使用该包？这就是今天的话题：“项目在构建打包时，Maven 如何引入本地 Jar 包？”

在这里插入图片描述

未收录原因

我们在开发时，经常会遇到某 Jar 包没有被 Maven 公共仓库收录的情况。公共仓库搜索：

阿里云代理仓库：https://developer.aliyun.com/mvn/search

mvnrepository仓库：https://mvnrepository.com/

未收录有以下几个原因：

开发者偏好。开发者个人或公司偏好，分享作品只在自己博客和官网上，或者只上传到 github 上。
历史原因。依赖资源创始时间太久远，那时候可能还没有 Maven，开发者延续习惯上传到原发布平台上，也未迁移或同步到 Maven 公共仓库。例如发布托管在 sourceforge 上。
闭源和版权原因。例如原来 Oracle 数据库的驱动包"ojdbc.jar"就是是闭源的，他们的法务部门很厉害，Oracle 如果不主动上传，公共仓库方也不敢随意引用，开发者每次只能在甲骨文官网下载驱动包。对于一个广泛应用的依赖包，开发时引入就相当麻烦。（现在 Oracle 已经将其同步到 Maven 公共仓库了，方便不少）

适合场景

引用的依赖不在 Maven 中央仓库或者企业内部私有仓库。
私人编写的包，或第三方公司提供的 Jar 包。（企业内部私有协议包/加密算法包等）
Maven 在内网离线开发。
引入被定制改动过的 Jar 包。

maven

解决方法：

Maven 坐标三要素：groupId、artifactId、version。假如有项目文件夹 C:/xxx/projectA，下面介绍两种方式引入本地 Jar 包。

一、mvn install 安装到本地仓库

mvn install 是 Maven 的一个命令，用于将项目的构建产物安装到本地仓库，以便其他项目可以作为依赖使用。将依赖的 Jar 包放入到项目 C:/xxx/projectA/lib 目录下。这里以 ojdbc 做示例：

<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8</artifactId>
    <version>23.5.0.24.07</version>
</dependency>

手动导入，依赖包目录下打开 cmd 命令提示符窗口，执行命令把 Jar 安装到本地仓库里：

mvn install:install-file -Dfile=ojdbc8.jar -DgroupId=com.oracle.database.jdbc -DartifactId=ojdbc8 -Dversion=23.5.0.24.07 -Dpackaging=jar

-Dfile=制品文件文件名（可以是制品路径）
-DgroupId=Maven坐标组织名称
-DartifactId=Maven坐标制品名称
-Dversion=Maven坐标制品版本
-Dpackaging=打包类型

依赖包比较多时，使用 bat 命令批量执行，在 C:/xxx/projectA/lib 目录下创建 install.bat 脚本文件：

@echo off
call mvn install:install-file -Dfile=xxx.jar -DgroupId=com.xxx -DartifactId=xxx-xxx -Dversion=21.1 -Dpackaging=jar
call mvn install:install-file -Dfile=xxx.jar -DgroupId=com.xxx -DartifactId=xxx-xxx -Dversion=21.1 -Dpackaging=jar
call mvn install:install-file -Dfile=xxx.jar -DgroupId=com.xxx -DartifactId=xxx-xxx -Dversion=21.1 -Dpackaging=jar
pause

你可以依照依赖包路径，前往本地仓库确认是否成功安装。

最后在 IDEA 里面刷新 Maven，重新加载 Jar 到项目就可以直接使用了。

二、修改项目 pom.xml 指定文件

拿到下载好的 Jar 包，在 IDEA 中，以下几步搞定 Maven 本地依赖：

将依赖的 Jar 包放入到项目 C:/xxx/projectA/lib 目录下（这里以 hutool 做示例）
项目 pom.xml 配置依赖 Jar 坐标和本地路径（scope/path）
配置 spring-boot-maven-plugin 编译时将引用本地 Jar 包

<!-- pom.xml 片段 -->
<dependencies>
    <dependency>
        <groupId>cn.hutool</groupId>
        <artifactId>hutool-all</artifactId>
        <version>5.8.18</version>
        <scope>system</scope>
        <systemPath>${project.basedir}/lib/hutool-all-5.8.18.jar</systemPath>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <mainClass>com.youngdream.demo.DemoApplication</mainClass>
                <!--maven将引用的本地 jar 包一起打包-->
                <includeSystemScope>true</includeSystemScope>
            </configuration>
        </plugin>
    </plugins>
</build>

依赖包的 scope 配置 system 范围时，必须通过 systemPath 指定依赖包的路径。表示此类依赖不经过 Maven 仓库解析，而是与本机系统绑定的，提交代码时就要注意了，该依赖包也得提交保存，以免后期管理丢失 Jar 包。

（题外话：这样直接上传的做法是简便开发起见，代码仓库拉下来就能直接用。实际上不建议把二进制文件放在 git上托管，会造成项目体积臃肿，大的二进制文件在上传时也会因为文件过大被拒绝，你可以尝试调整 Git http 或者 ssh 的 buffer 大小，或者使用 Git LFS 解决这个问题。）

IDE