很多Java开发者都有过这样的经历:项目能跑起来,但依赖下载却慢得像蜗牛爬,或者干脆报错告诉你找不到某个依赖。你打开pom.xml检查了一遍又一遍,依赖坐标没写错,版本也对得上,可就是不行。最后折腾半天,发现是settings.xml里的配置乱了套。这个文件是Maven的全局配置,但它生效的次序、跟pom.xml的关系、以及镜像和仓库的优先级,很多人其实没理清楚。

这篇文章咱们就用大白话,把settings.xml里镜像、仓库和代理的生效次序理一理,再结合国内加速和离线受限的常见场景,给出具体的配置示例和排错细节。

一、先搞懂生效次序:镜像、仓库、代理到底听谁的?

1.1 settings.xml 和 pom.xml 的“权力游戏”

Maven有两个核心配置文件,一个是项目的pom.xml,另一个是用户级的settings.xml。很多人以为pom.xml是老大,其实在依赖下载这件事上,settings.xml的权力更大。

pom.xml里可以配置仓库,但settings.xml里也可以配置仓库。如果两边都配了,settings.xml的优先级更高,会覆盖pom.xml的仓库配置。这就像你去超市买东西,会员价和普通价都写着,但收银员会优先按会员价结账,因为会员价是更“全局”的规则。

settings.xml还有一个特殊权限:它可以定义镜像,用来“拦截”对特定仓库的访问。这个拦截动作发生在依赖解析的早期,甚至比pom.xml里的仓库还要早。也就是说,当你请求一个依赖时,Maven会先看settings.xml里有没有镜像匹配这个请求,如果有,就直接走镜像,根本不会去访问pom.xml里定义的原始仓库。

1.2 镜像与仓库:谁先拦截谁?

镜像(Mirror)的作用是把某个远程仓库的地址“偷换”成另一个地址。比如你想访问中央仓库,但中央仓库在国外太慢,你可以设置一个镜像,把所有对中央仓库的请求都转发到阿里云的仓库。这个“偷换”是全局的,只要匹配规则写了,它就生效。

仓库(Repository)则是真正存放依赖的地方,包括本地仓库和远程仓库。远程仓库可以是中央仓库、阿里云仓库、你公司的私有仓库等。settings.xml可以定义远程仓库,pom.xml也可以定义,但settings.xml优先。

生效次序是这样:依赖请求先经过镜像拦截,如果有镜像匹配,就直接走镜像地址,后面的仓库配置根本不看。如果没有匹配的镜像,才继续走仓库配置,这时候settings.xml里的仓库又优先于pom.xml里的仓库。

这里有个容易踩的坑:如果你在settings.xml里配了一个镜像,但镜像的mirrorOf写错了,比如写成了central,那只有中央仓库的请求会被拦截,其他仓库不受影响。如果你想让所有请求都走镜像,得写*。很多人只写了central,结果公司私有仓库的请求还是直连,导致内网请求超时,还找不到原因。

1.3 代理:网络层面的“过路费”

代理(Proxy)跟镜像和仓库不是一个层面的东西。代理是JVM网络层的配置,它影响的是所有HTTP/HTTPS请求,不只是Maven的依赖下载。比如你在公司内网,访问外网需要走代理,那Maven下载依赖也会被代理拦截。

生效次序上,代理是最先的,因为它作用于网络底层。不管你是走镜像还是走仓库,最终都要发起网络请求,而代理会先判断这个请求需不需要走代理服务器。所以如果你公司需要代理,但你只在settings.xml里配了镜像,没配代理,那么依赖下载依然会失败,因为网络层就断了。

代理的配置要注意:active必须设为true,否则不生效。还有nonProxyHosts,这是给内网地址用的,比如你的私有仓库地址,应该把它排除在代理之外,否则内网请求也会走外网代理,反而更慢。

二、国内加速:阿里云镜像让下载飞起来

2.1 为什么默认中央仓库这么慢?

Maven的中央仓库默认地址是https://repo.maven.apache.org/maven2,服务器在海外。从国内访问,网络延迟高,带宽小,下载一个几十MB的依赖可能要好几分钟,甚至超时失败。这是很多国内开发者的痛点。

解决思路很简单:设置一个国内镜像,把中央仓库的地址“偷换”成国内加速地址。阿里云、华为云、腾讯云都有提供Maven仓库加速服务,其中阿里云的公共仓库最常用。

2.2 配置阿里云镜像的完整示例

技术栈统一为Maven。下面是一个完整的settings.xml镜像配置片段,你可以直接放到~/.m2/settings.xml里(Windows用户是C:\Users\你的用户名\.m2\settings.xml)。

<!-- settings.xml 示例:配置阿里云镜像加速中央仓库 -->
<settings>
  <!-- 镜像配置,多个镜像可以同时存在,但匹配规则不同 -->
  <mirrors>
    <!-- 第一个镜像:阿里云公共仓库 -->
    <mirror>
      <!-- 镜像ID,全局唯一,不要跟仓库ID重复 -->
      <id>aliyunmaven</id>
      <!-- 镜像的地址,阿里云公共仓库,包含中央仓库、JCenter、Spring等 -->
      <url>https://maven.aliyun.com/repository/public</url>
      <!-- 匹配所有仓库,包括中央仓库和自定义仓库 -->
      <!-- 写 * 表示拦截所有请求,这是最常用的配置 -->
      <mirrorOf>*</mirrorOf>
    </mirror>
  </mirrors>
</settings>

上面的示例用了<mirrorOf>*</mirrorOf>,意思是所有仓库请求都走阿里云。这样配置有一个副作用:如果你在pom.xml里配置了公司私有仓库,请求也会被拦截到阿里云,私有仓库就失效了。

如果你既想用阿里云加速中央仓库,又想保留私有仓库,需要更精确的匹配。比如:

<settings>
  <mirrors>
    <mirror>
      <id>aliyun-central</id>
      <url>https://maven.aliyun.com/repository/public</url>
      <!-- 只拦截中央仓库,不影响其他仓库 -->
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

但这样写,如果pom.xml里还配置了其他远程仓库,那些仓库请求不会走阿里云,而是直连,可能还是会慢。更稳妥的方案是用<mirrorOf>*,!private-repo</mirrorOf>,表示拦截所有仓库,但排除private-repo这个仓库ID。

<settings>
  <mirrors>
    <mirror>
      <id>aliyun-with-exclusion</id>
      <url>https://maven.aliyun.com/repository/public</url>
      <!-- 拦截所有仓库,除了ID为private-repo的仓库 -->
      <mirrorOf>*,!private-repo</mirrorOf>
    </mirror>
  </mirrors>
</settings>

这个写法特别实用,尤其是有私有仓库的团队。!表示排除,多个排除用逗号分隔。需要注意,mirrorOf不支持正则表达式,只支持*、!和具体的仓库ID,所以别写复杂逻辑。

三、离线受限环境:不联网也能跑项目

3.1 离线环境的需求分析

有些开发环境是内网隔离的,根本访问不了外网,但项目又需要依赖。这时候不能靠镜像,也不能靠代理,因为网络物理上不通。解决方案是:预先在能联网的机器上把依赖下载到本地仓库,然后把整个.m2目录打包拷贝到内网机器上,再配置Maven离线模式。

本地仓库(Local Repository)就是存放已下载依赖的目录,默认是~/.m2/repository。当你联网时,Maven会从远程仓库下载依赖并缓存在这里。离线环境下,只要本地仓库里有对应的依赖,Maven就不会去请求远程仓库,而是直接使用本地缓存。

3.2 本地仓库与离线模式的配置

离线环境需要两步:第一步配置本地仓库路径,第二步设置离线模式。本地仓库路径在settings.xml里通过<localRepository>指定,离线模式有两种方式:一是在settings.xml里设置<offline>true</offline>,二是命令行加-o参数。

下面是一个完整的离线环境配置示例。

<!-- settings.xml 示例:配置本地仓库路径和离线模式 -->
<settings>
  <!-- 本地仓库路径,建议放在非系统盘,且路径不要包含中文 -->
  <localRepository>/data/maven-repo</localRepository>
  
  <!-- 离线模式,设置为true后,Maven只访问本地仓库,不请求远程 -->
  <offline>true</offline>
</settings>

但注意,如果<offline>设为true,但本地仓库里缺少某个依赖,Maven会直接报错,不会尝试联网。这跟命令行-o的效果是一样的。所以离线模式只适合本地仓库已经准备好的情况。

如果你不想改settings.xml,只想临时用一次离线模式,可以这样执行:

# 离线构建,使用本地仓库,不联网
mvn -o clean package

-o就是--offline的缩写。这里有个细节:即使设置了离线模式,如果pom.xml里引用了<repositories>,Maven还是会尝试去解析这些仓库,但因为没有网络,会直接失败。所以离线环境下,pom.xml里最好不要配置远程仓库,或者保证本地仓库里已经有对应依赖。

另外一个实用技巧:在联网机器上,可以用mvn dependency:go-offline预下载所有依赖。这个命令会读取pom.xml,把所有需要的依赖(包括传递依赖)都下载到本地仓库。

# 预下载依赖到本地仓库,供离线环境使用
mvn dependency:go-offline

这个命令执行完,~/.m2/repository里就有全部依赖了。然后把整个~/.m2目录打包,拷到内网机器上解压,再配置离线模式,项目就能正常构建了。

四、代理配置:公司网络下的“通行证”

4.1 代理的适用场景

有些公司网络比较特殊,比如要求所有外网请求必须经过指定的代理服务器,否则不能访问互联网。这时候Maven下载依赖也会失败,需要配置代理。代理的配置在settings.xml的<proxies>标签里。

代理和镜像的区别:镜像改变了依赖的下载地址,代理只是增加了网络中转。镜像解决的是“地址太慢”的问题,代理解决的是“网络不通”的问题。两者可以同时使用,比如既走镜像加速,又走代理上网。

4.2 配置代理的完整示例

下面是代理配置的完整示例。注意,如果你在内网,代理的nonProxyHosts一定要包含内网仓库的地址,否则内网请求也会走代理,反而绕远。

<!-- settings.xml 示例:配置HTTP代理 -->
<settings>
  <proxies>
    <proxy>
      <!-- 代理ID,唯一即可 -->
      <id>company-http-proxy</id>
      <!-- 代理协议,常见是http,也可能是https -->
      <protocol>http</protocol>
      <!-- 代理服务器主机名或IP -->
      <host>proxy.company.com</host>
      <!-- 代理服务器端口 -->
      <port>8080</port>
      <!-- 代理用户名,没有则留空 -->
      <username>dev_user</username>
      <!-- 代理密码,没有则留空 -->
      <password>p@ssw0rd</password>
      <!-- 是否启用这个代理 -->
      <active>true</active>
      <!-- 非代理主机列表,用竖线分隔 -->
      <!-- 内网地址和本地仓库地址走直连,不走代理 -->
      <nonProxyHosts>localhost|127.0.0.1|*.internal.com|10.*.*.*</nonProxyHosts>
    </proxy>
  </proxies>
</settings>

代理配置有几个细节要注意。第一,<protocol>可以是http或https,如果代理服务器本身是HTTPS,就写https。第二,<username>和<password>如果不需要认证,可以省略。第三,<nonProxyHosts>支持通配符,比如*.internal.com表示所有以.internal.com结尾的域名都不走代理。第四,如果有多个代理,Maven会按顺序找第一个<active>true的代理使用,所以最好只配一个激活的。

如果代理配置不生效,可以用一个简单的命令验证:

# 查看Maven实际生效的代理配置
mvn help:effective-settings

这个命令会输出Maven最终加载的settings.xml内容,你可以检查<proxies>里的active是否为true,以及host和port是否正确。

五、排错细节:配置不生效的常见坑

5.1 检查生效配置的命令

很多时候配置没生效,不是配置写错了,而是Maven加载了错误的settings.xml。Maven默认会加载两个位置的settings.xml:全局的(Maven安装目录下的conf/settings.xml)和用户级的(~/.m2/settings.xml)。用户级会覆盖全局,但如果你在用户级里写错了语法,Maven会报错并回退到全局配置,这时候你可能根本没意识到。

用下面的命令查看实际加载的配置:

# 查看当前生效的settings.xml路径
mvn -X help:effective-settings | grep -A2 "user settings"

或者更直接:

# 输出所有生效配置,包括本地仓库路径、镜像、代理等
mvn help:effective-settings

如果输出的localRepository不是你配置的路径,说明配置没被加载。常见原因是文件路径错误、XML语法错误、或者文件编码不对(settings.xml必须用UTF-8编码)。

5.2 清理本地仓库的失败文件

有时候镜像配置正确,但下载依然失败,这是因为本地仓库里有残留的.lastUpdated文件。当Maven下载依赖失败时,会生成一个.lastUpdated文件,记录失败时间。默认情况下,Maven会在24小时内不重试这个依赖,即使你修好了镜像配置,它也不会重新下载。

这时候需要手动清理这些失败文件。

# 清理所有.lastUpdated文件,强制Maven重新下载
find ~/.m2/repository -name "*.lastUpdated" -exec rm -rf {} \;

清理后再执行构建,Maven就会重新发起下载请求。这个坑特别常见,很多开发者改了镜像地址,但忘记清理.lastUpdated文件,导致一直报错,还以为配置没生效。

另外还有一个细节:mirrorOf匹配规则里,如果写的是central,但你的pom.xml里配置了<repositories>,并且仓库ID不是central,那镜像不会拦截这些仓库。这时候可以尝试把mirrorOf改成*,或者用*,!你的私有仓库ID来精确控制。

六、总结

settings.xml的配置其实不复杂,关键是把生效次序理清楚:代理在网络最底层,影响所有请求;镜像在依赖解析早期,拦截特定仓库;仓库配置决定依赖从哪来,settings.xml优先于pom.xml。国内加速用阿里云镜像,mirrorOf写*最省事,但私有仓库要用*,!排除;离线环境用本地仓库加离线模式,-o参数临时用,<offline>永久用;代理配置注意nonProxyHosts排除内网地址。排错时先用mvn help:effective-settings确认配置加载,再清理.lastUpdated文件解决重复下载失败问题。多试几次,你就能把这些配置用得飞起。