Maven 配置中的 `＜mirror＞` ：如何绕过 HTTP 阻断机制

原创于 2025-06-12 09:00:00 发布 · 1.1k 阅读

15 ·

CC 4.0 BY-SA版权

文章标签：

#maven #http #java

Maven 专栏收录该内容

8 篇文章

订阅专栏

一、问题场景：升级 Maven 后构建失败

如果你在使用 Maven 3.8.1 及以上版本 时，突然遇到以下错误提示：

[ERROR] The HTTP repository protocol is not supported. Use HTTPS instead.

这通常意味着 Maven 默认 禁止使用 HTTP 协议 的仓库（例如 http://repo.maven.apache.org/maven2），以提高安全性。此时，如果你的项目依赖的某些仓库必须通过 HTTP 访问（例如公司内网私有仓库或历史遗留项目），构建将直接失败。

二、解决方案：通过 `<mirror>` 配置覆盖默认行为

1. 配置示例

在 Maven 的 settings.xml 文件中添加以下配置：

<mirror>
    <id>maven-default-http-blocker</id>
    <mirrorOf>dummy</mirrorOf>
    <name>Dummy mirror to override default blocking mirror</name>
    <url>http://0.0.0.0/</url>
</mirror>

2. 配置解析

元素名	作用
`<id>`	镜像的唯一标识符，此处使用 Maven 官方定义的 `maven-default-http-blocker`。
`<mirrorOf>`	`dummy` 是一个特殊值，表示此镜像不会匹配任何仓库（无效匹配）。
`<url>`	`http://0.0.0.0/` 是一个无效地址，用于绕过 Maven 的 HTTP 阻断逻辑。

三、Maven 的 HTTP 阻断机制背景

1. 背景知识

Maven 3.8.1 版本引入：从该版本开始，默认 禁止使用 HTTP 协议 的仓库，强制要求使用 HTTPS。
目的：防止中间人攻击（MITM），确保依赖下载过程的安全性。

2. 默认行为

如果项目中配置了 HTTP 仓库（如 <url>http://...</url>），Maven 会抛出错误并终止构建。
如果未配置 HTTP 仓库，但依赖的远程仓库（如中央仓库）通过 HTTP 访问，Maven 也会报错。

四、此配置的作用与原理

1. 核心作用

覆盖默认阻断规则：通过配置一个无效的镜像，Maven 会认为已经为 HTTP 仓库设置了镜像，从而 跳过默认的 HTTP 阻断检查。
解决构建失败：允许项目继续使用 HTTP 仓库，避免因协议限制导致的构建中断。

2. 技术原理

Maven 在初始化时会检查所有仓库的 URL 协议。
如果发现 HTTP 协议且未配置对应的 HTTPS 镜像，则触发阻断。
通过配置一个 <mirrorOf>dummy</mirrorOf> 的镜像（即使 URL 无效），Maven 会认为 HTTP 仓库已被镜像覆盖，从而 不再执行阻断逻辑。

五、此配置的潜在问题与风险

1. 无效的 URL 导致的问题

http://0.0.0.0/ 是无效地址：此配置仅用于绕过阻断，实际不会生效。如果项目依赖的仓库仍需通过 HTTP 访问，构建最终仍会失败。
正确做法：将 <url> 替换为 有效的 HTTPS 仓库地址，例如：
```
<url>https://repo.maven.apache.org/maven2</url>
```

2. 安全性风险

HTTP 协议不安全：数据传输未加密，容易被中间人攻击。
建议：优先使用 HTTPS 仓库，仅在 无法修改仓库协议 的情况下使用此配置。

六、正确的配置示例

1. 绕过 HTTP 阻断（推荐）

如果需要临时绕过 HTTP 阻断（例如内网仓库必须使用 HTTP），可以配置如下：

<mirror>
    <id>http-mirror</id>
    <mirrorOf>central</mirrorOf>  <!-- 假设你要覆盖中央仓库 -->
    <url>https://repo.maven.apache.org/maven2</url>  <!-- 使用 HTTPS 地址 -->
</mirror>

2. 强制禁用 HTTP 阻断（不推荐）

如果确实需要禁用 HTTP 阻断（例如项目依赖 HTTP 仓库），可配置如下：

<mirror>
    <id>http-blocker-bypass</id>
    <mirrorOf>!</mirrorOf>  <!-- 匹配所有仓库 -->
    <url>http://0.0.0.0/</url>
</mirror>

七、优势与适用场景

1. 优势

快速解决问题：无需修改项目依赖配置，直接通过 settings.xml 绕过 HTTP 阻断。
兼容旧项目：适用于依赖 HTTP 仓库的旧项目，避免因 Maven 版本升级导致构建失败。
临时过渡方案：为迁移到 HTTPS 仓库提供缓冲期。

2. 适用场景

公司内网私有仓库仅支持 HTTP。
项目依赖的第三方仓库未提供 HTTPS。
紧急修复构建问题，后续计划迁移到 HTTPS。

八、最佳实践建议

1. 优先使用 HTTPS 仓库

修改仓库地址：将所有 HTTP 仓库替换为 HTTPS。
升级私有仓库：确保内部仓库支持 HTTPS 协议。

2. 明确配置 `<mirrorOf>`

避免使用 dummy 或 !，而是指定具体的仓库 ID（如 central）。

示例：

<mirror>
    <id>central-mirror</id>
    <mirrorOf>central</mirrorOf>
    <url>https://repo.maven.apache.org/maven2</url>
</mirror>

3. 验证配置有效性

运行测试命令：
```
mvn dependency:resolve -X
```
检查日志中是否显示使用了正确的镜像地址。