maven代理

Maven 代理配置：内网环境下访问仓库的解决方案

在企业内网环境中，由于网络限制，Maven 可能无法直接访问中央仓库或外部镜像。此时需要通过配置代理服务器，让 Maven 借助代理实现仓库访问。本文将详细讲解 Maven 代理的配置方法及注意事项。

代理配置的核心场景

需要配置 Maven 代理的典型场景包括：

• 公司内网限制直接访问外网，必须通过指定代理服务器。
• 访问某些地区受限的仓库（如国外仓库），需通过特定代理加速。
• 企业内部网络安全策略要求所有外部请求经过代理审计。

代理配置的位置与格式

Maven 代理配置在 settings.xml 文件中（全局配置：${MAVEN_HOME}/conf/settings.xml；用户级配置：~/.m2/settings.xml），使用 <proxies> 标签定义。

基础配置模板

<settings>
  <!-- 其他配置... -->
  
  <proxies>
    <!-- 代理配置（可配置多个，通过 <active> 控制激活） -->
    <proxy>
      <id>company-proxy</id> <!-- 代理唯一标识，用于区分多个代理 -->
      <active>true</active> <!-- 是否激活该代理（true/false） -->
      <protocol>http</protocol> <!-- 代理协议（http/https/socks） -->
      <username>your-username</username> <!-- 代理认证用户名（可选） -->
      <password>your-password</password> <!-- 代理认证密码（可选） -->
      <host>proxy.example.com</host> <!-- 代理服务器地址（必填） -->
      <port>8080</port> <!-- 代理服务器端口（必填） -->
      <!-- 无需走代理的地址（用 | 分隔，支持通配符 *） -->
      <nonProxyHosts>localhost|127.0.0.1|*.company.com</nonProxyHosts>
    </proxy>
  </proxies>
</settings>

配置参数详解

参数	含义	必填	说明
<id>	代理的唯一标识	否	多个代理时用于区分，建议命名有意义（如 http-proxy、socks-proxy）。
<active>	是否激活代理	是	true 表示启用该代理，同一时间只能有一个代理被激活。
<protocol>	代理协议	是	支持 http、https、socks（需 Maven 3.0.4+ 支持 SOCKS 代理）。
<username>	代理认证用户名	否	若代理服务器需要身份验证，则填写。
<password>	代理认证密码	否	与用户名配套使用，明文存储（敏感信息需注意安全）。
<host>	代理服务器主机名 / IP	是	如 proxy.company.com 或 192.168.1.100。
<port>	代理服务器端口	是	如 8080、3128（常见代理端口）。
<nonProxyHosts>	无需代理的地址	否	支持通配符 *（匹配任意字符）和 `	（分隔多个地址），如*.internal.com` 表示内部域名无需代理。

特殊场景配置

1. 同时配置 HTTP 和 HTTPS 代理

若需要分别为 HTTP 和 HTTPS 协议配置不同代理，可定义两个代理并通过 <protocol> 区分：

<proxies>
  <!-- HTTP 代理 -->
  <proxy>
    <id>http-proxy</id>
    <active>true</active>
    <protocol>http</protocol>
    <host>http-proxy.example.com</host>
    <port>8080</port>
  </proxy>
  
  <!-- HTTPS 代理（需单独配置） -->
  <proxy>
    <id>https-proxy</id>
    <active>true</active>
    <protocol>https</protocol>
    <host>https-proxy.example.com</host>
    <port>8443</port>
  </proxy>
</proxies>

注意：Maven 3.8.1+ 对 HTTP 仓库有默认限制，建议优先使用 HTTPS 代理。

2. SOCKS 代理配置

对于 SOCKS 代理（如翻墙工具提供的代理），配置方式如下：

<proxy>
  <id>socks-proxy</id>
  <active>true</active>
  <protocol>socks</protocol> <!-- 协议为 socks -->
  <host>127.0.0.1</host> <!-- SOCKS 代理地址（如本地翻墙工具） -->
  <port>1080</port> <!-- SOCKS 常见端口 -->
  <nonProxyHosts>localhost|*.internal.com</nonProxyHosts>
</proxy>

3. 无认证代理

若代理服务器无需用户名密码，省略 <username> 和 <password> 即可：

<proxy>
  <id>no-auth-proxy</id>
  <active>true</active>
  <protocol>http</protocol>
  <host>proxy.example.com</host>
  <port>8080</port>
  <nonProxyHosts>*.company.com</nonProxyHosts>
</proxy>

验证代理配置是否生效

配置完成后，可通过以下方式验证代理是否生效：

1. 执行简单命令测试：

   mvn help:system

   该命令会下载 Maven 系统信息，若代理生效，会显示从仓库下载资源的日志（如 Downloaded from ...）。

2. 查看调试日志：
   若不确定代理是否被使用，可添加 -X 参数查看详细日志：

   mvn package -X | grep "proxy"  # 过滤与代理相关的日志

   生效的代理会在日志中显示，如 Using proxy: proxy.example.com:8080。

3. 检查依赖下载：
   创建一个简单项目，添加一个中央仓库的依赖（如 junit），执行 mvn compile，若依赖能正常下载，则代理配置正确。

常见问题与解决方案

1. 代理配置正确但无法访问仓库

可能原因：

• 代理服务器端口或协议错误（如将 https 写成 http）。
• nonProxyHosts 配置错误，导致目标仓库被误判为无需代理。
• 企业防火墙额外限制了代理访问特定仓库。

解决：

• 检查 protocol、host、port 是否与代理服务器信息一致。
• 暂时注释 <nonProxyHosts> 测试是否因该配置导致问题。
• 联系网络管理员确认代理权限。

2. 代理需要认证但提示权限不足

错误提示：Failed to retrieve plugin descriptor for ...: Authorization failed

解决：

• 确认 <username> 和 <password> 正确（注意大小写）。
• 若密码包含特殊字符（如 转义为 $）。

3. 多个代理如何切换

解决：通过修改 <active> 标签的值切换激活的代理，同一时间仅一个代理生效：

<proxy>
  <id>proxy1</id>
  <active>false</active> <!-- 禁用 -->
  <!-- 其他配置 -->
</proxy>
<proxy>
  <id>proxy2</id>
  <active>true</active> <!-- 启用 -->
  <!-- 其他配置 -->
</proxy>