Maven 引入外部依赖（本地 JAR / 非中央仓库）完全指南（2025 最新版）

一句话总结：
Maven 优先中央仓库 → 找不到？用 system / install:install-file / 本地仓库 解决！

---

一、场景分类（你属于哪种？）

场景	推荐方式
公司内部 JAR	mvn install:install-file → 本地仓库
第三方未发布 JAR	install:install-file 或 system
临时测试 JAR	<scope>system</scope>
企业级统一管理	Nexus 私有仓库（最佳）

---

二、方法 1：system 范围（临时 / 不推荐长期使用）

适用：快速测试、本地 JAR

<dependency>
    <groupId>com.company</groupId>
    <artifactId>external-lib</artifactId>
    <version>1.0.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/external-lib-1.0.0.jar</systemPath>
</dependency>

项目结构：

my-project/
├── pom.xml
├── lib/
│   └── external-lib-1.0.0.jar   ← 手动放入
└── src/...

缺点：

• 不传递
• 路径依赖，别人无法构建
• 不参与版本管理

仅用于临时调试！

---

三、方法 2：mvn install:install-file（推荐！）

步骤：将本地 JAR 安装到 本地仓库

mvn install:install-file \
  -Dfile=/path/to/external-lib-1.0.0.jar \
  -DgroupId=com.company \
  -DartifactId=external-lib \
  -Dversion=1.0.0 \
  -Dpackaging=jar

成功输出：

[INFO] Installing /path/to/external-lib-1.0.0.jar to 
~/.m2/repository/com/company/external-lib/1.0.0/external-lib-1.0.0.jar

然后在 pom.xml 正常引入：

<dependency>
    <groupId>com.company</groupId>
    <artifactId>external-lib</artifactId>
    <version>1.0.0</version>
</dependency>

优点：

• 标准 GAV 坐标
• 支持传递性依赖
• 团队可共享（复制 ~/.m2 或用 Nexus）

---

四、方法 3：项目内 lib/ + 自动安装（多 JAR 推荐）

1. 创建 lib/ 目录

my-project/
├── lib/
│   ├── jdbc-driver.jar
│   └── utils-2.1.jar
├── pom.xml
└── install-libs.xml   ← 辅助 POM

2. 创建 install-libs.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>install-libs</artifactId>
    <version>1.0</version>
    <packaging>pom</packaging>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-install-plugin</artifactId>
                <version>3.1.1</version>
                <executions>
                    <execution>
                        <id>install-jdbc</id>
                        <phase>validate</phase>
                        <goals><goal>install-file</goal></goals>
                        <configuration>
                            <file>${project.basedir}/lib/jdbc-driver.jar</file>
                            <groupId>com.mysql</groupId>
                            <artifactId>mysql-connector</artifactId>
                            <version>8.0.33</version>
                            <packaging>jar</packaging>
                        </configuration>
                    </execution>
                    <execution>
                        <id>install-utils</id>
                        <phase>validate</phase>
                        <goals><goal>install-file</goal></goals>
                        <configuration>
                            <file>${project.basedir}/lib/utils-2.1.jar</file>
                            <groupId>com.company</groupId>
                            <artifactId>utils</artifactId>
                            <version>2.1</version>
                            <packaging>jar</packaging>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

3. 构建时自动安装

mvn validate -f install-libs.xml
mvn clean package

---

五、方法 4：Nexus 私有仓库（企业级最佳）

流程：

1. 公司搭建 Nexus 或 Artifactory
2. 上传 JAR 到私有仓库
3. pom.xml 配置 <repositories>

<repositories>
    <repository>
        <id>nexus</id>
        <url>http://nexus.company.com/repository/maven-public/</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.company</groupId>
    <artifactId>internal-lib</artifactId>
    <version>1.0.0</version>
</dependency>

---

六、方法 5：flatDir（Gradle 风格，Maven 不原生支持）

Maven 不支持 flatDir，只能用 install:install-file

---

七、完整示例：引入 MySQL 驱动（经典）

方式 A：推荐（中央仓库已有）

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.0.33</version>
</dependency>

方式 B：本地 JAR（旧版本）

mvn install:install-file \
  -Dfile=lib/mysql-connector-java-5.1.49.jar \
  -DgroupId=mysql \
  -DartifactId=mysql-connector-java \
  -Dversion=5.1.49 \
  -Dpackaging=jar

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>5.1.49</version>
</dependency>

---

八、常见问题解决

问题	解决方案
systemPath 找不到	用 ${project.basedir}
构建失败 No compiler	安装 JAR 后 mvn clean
团队无法构建	用 install-libs.xml 或 Nexus
JAR 有依赖	必须一起 install 所有 JAR

---

九、最佳实践总结

场景	推荐方式
临时调试	<scope>system</scope>
个人项目	mvn install:install-file
团队协作	install-libs.xml + Git
企业项目	Nexus 私有仓库

---

十、一键脚本（复制粘贴）

# 安装单个 JAR
install_jar() {
    local file=$1
    local groupId=$2
    local artifactId=$3
    local version=$4
    mvn install:install-file -Dfile="$file" -DgroupId="$groupId" -DartifactId="$artifactId" -Dversion="$version" -Dpackaging=jar
}

# 使用
install_jar "./lib/ocr-sdk.jar" "com.baidu" "ocr-sdk" "1.0.0"

---

恭喜！你已掌握 Maven 引入外部依赖！

---

下一步推荐

方向	内容
Nexus 搭建	Docker 一键部署
自动上传	mvn deploy:deploy-file
JAR 瘦身	maven-dependency-plugin

---

需要 Nexus 私有仓库 + 自动上传脚本？
回复 Nexus Deploy 立即获取！