一、前言

平时开发中，大部分依赖直接在 Maven 写坐标即可自动下载。但是有一类 Jar 包永远无法从公共仓库下载：商业授权 SDK、闭源第三方 Jar、公司内部工具包，例如 SuperMap、ArcGIS、国产中间件等。

本次我以 SuperMap 超图 Jar 升级替换为例，完整记录 Maven 手动安装、替换 Jar 的全过程，以及大量新手必踩坑点。

二、常见误区：为什么普通依赖不用安装，SuperMap 需要？

1. 公共开源包（无需手动安装）

例如：Spring、Mybatis、Mysql、Lombok、Hutool。

• 存放在：阿里云仓库 / Maven 中央仓库

• 使用方式：直接改版本号，刷新 Maven 自动下载

• 不需要任何命令，不需要本地 Jar

2. 商业/私有 Jar（必须手动安装）

例如：SuperMap、ArcGIS、付费SDK、自研Jar。

• 公共仓库没有资源

• Maven 无法联网下载

• 必须开发者手动把 Jar 放入本地 Maven 仓库

• 手动放入仓库的动作：mvn install:install-file 安装

三、完整实操步骤（替换 SuperMap 为例）

1. 准备工作

拿到新版本的若干 Jar 包，本次用到超图5个核心依赖：

• com.supermap.data

• com.supermap.data.conversion

• com.supermap.mapping

• com.supermap.layout

• com.supermap.analyst.spatialanalyst

2. 环境要求（新手必看）

必须配置 Maven 系统环境变量，保证 CMD 输入 mvn -v 能识别。

踩坑：IDEA 内置 PowerShell 不会加载最新环境变量，建议使用系统CMD执行安装命令。

3. Jar 命名规范（非常重要）

Jar 文件名必须带版本号，例如：

com.supermap.data-12.0.1.jar

原因：Maven 依赖定位规则：groupId + artifactId + version，三者必须严格匹配。

如果不带版本号，安装命令识别不到文件，直接报错：文件不存在。

4. 执行安装命令

将 Jar 放入 pom.xml 同级目录，CMD 进入当前项目目录。

示例单条安装命令：

mvn install:install-file -Dfile=com.supermap.data-12.0.1.jar -DgroupId=com.supermap -DartifactId=com.supermap.data -Dversion=12.0.1 -Dpackaging=jar

出现 BUILD SUCCESS 代表安装成功。

4.1 补充：一定要在 pom.xml 同级目录执行吗？

结论：不是必须，但新手强烈建议放在同级目录。

1、原理直白解释

Maven 安装命令中 -Dfile=xxx.jar是相对路径：

你当前 CMD 在哪一个文件夹，它就去哪一个文件夹找 Jar。

如果你写的是单纯文件名（不带完整路径），Jar 就必须和 CMD 工作目录保持一致。

2、为什么教程都放 pom 同级？

• 路径最简单，不用写超长绝对路径

• 不容易出现 Jar not exists 文件找不到报错

• 方便管理临时 Jar，安装完统一删除

3、不在同级目录怎么写？（进阶写法）

可以放在任意磁盘位置，只要写绝对路径，示例：

mvn install:install-file -Dfile=E:\jar\com.supermap.data-12.0.1.jar -DgroupId=com.supermap -DartifactId=com.supermap.data -Dversion=12.0.1 -Dpackaging=jar

4、误区提醒

安装命令不需要依赖 pom.xml，哪怕没有 pom 文件，这条命令照样能把 Jar 装进 Maven 仓库。

很多人误以为必须在项目目录执行，这是错误认知。

唯一限制：文件路径必须写对。

5. 安装完成后，原始Jar可以删除吗？

可以直接删除！！！

安装本质：把Jar复制一份放入你的 Maven 本地仓库（例如 D:\MavenRepository）。

项目后续编译、运行、打包，全部读取仓库内的文件，项目目录下的原始Jar只是临时安装介质，无任何作用。

6. IDEA 刷新依赖

右侧 Maven 面板 → 刷新按钮，依赖红叉消失，版本替换完成。

四、本次踩坑大全（强烈收藏）

1. PowerShell 无法识别 mvn
   原因：PowerShell 不会实时加载新配置的环境变量，解决方案：使用系统CMD。

2. 提示xxx.jar not exists
   原因：文件名不一致、没有版本号、路径不对。

3. mvnw 命令报错
   原因：普通Maven项目没有mvnw脚本，不要无脑复制网上教程。

4. 明明装了依赖还是爆红
   解决方案：刷新Maven、清除IDEA缓存、重启项目。

五、通俗易懂总结（直白人话）

1. 公共开源包：改版本号+刷新，无需安装。

2. 商业私有包：必须手动mvn安装进本地仓库。

3. 安装命令本质：复制Jar+登记坐标。

4. 安装完原始Jar可以删除，不影响项目。

5. Jar名称必须带版本号，严格匹配pom依赖。

6. 新手尽量用系统CMD，不要用IDEA终端。

六、附加：通用安装模板（可永久收藏）

mvn install:install-file -Dfile=你的jar文件名.jar -DgroupId=公司组名 -DartifactId=项目名 -Dversion=版本号 -Dpackaging=jar