前两天帮同事排查一个构建问题，项目从 Maven 3.6.3 升到 3.8.6 之后，原本一直正常的公司私服突然拉不了依赖，报错里赫然写着Blocked mirror for repository: nexus。我第一反应是私服挂了，但浏览器打开私服地址明明好好的；第二反应是镜像配置写错了，可翻来覆去看 settings.xml 也就那几行。折腾了大半天，最后才意识到问题根本不在我们自己配的镜像，而是 Maven 3.8 默认 settings.xml 里新加的那个带blocked标签的拦截器。
如果你也遇到过类似报错，或者刚升级 Maven 版本后内网依赖大面积下载失败，这篇就是为你写的。下面我把这次的排查过程、底层原因、修复方案和容易踩的坑一次性讲清楚。
1. Blocked mirror 报错全解析：从现象到真凶
1.1 报错现场长什么样
先看一段典型报错，遇到的时候不要慌，它比大部分 Maven 报错都要诚实：
[ERROR] Failed to execute goal on project demo: Could not resolve dependencies for project com.example:demo:jar:1.0.0: Failed to collect dependencies at com.example:lib:1.0: Failed to read artifact descriptor for com.example:lib:1.0: Could not transfer artifact com.example:lib:1.0:pom:1.0 from/to nexus (http://192.168.10.20:8081/repository/maven-public/): Blocked mirror for repository: nexus注意最后一行：Blocked mirror for repository: nexus。这里的nexus是你定义的 repository id，也就是在 pom.xml 或者 settings.xml 里给某个仓库起的名字，不一定是 mirror 的 id。很多同学第一次看到这行，会去 settings.xml 里找一个叫 nexus 的 mirror，结果找不到，然后就懵了。这里的逻辑是：Maven 按规则给仓库nexus匹配到了一个被标记为blocked的 mirror，于是拒绝执行下载动作。
也就是说，报错描述的不是“某个镜像损坏了”，而是“某个镜像被 Maven 主动禁止使用了”。
1.2 Maven 3.8 为什么突然多了个拦截器
Maven 3.8.0 发布时有一个容易被忽略的改动：官方在默认的全局配置文件MAVEN_HOME/conf/settings.xml里加入了一个特殊的 mirror，专门用来阻止外部 HTTP 仓库的请求。默认配置内容如下：
<mirror> <id>maven-default-http-blocker</id> <mirrorOf>external:http:*</mirrorOf> <name>Pseudo repository to mirror external repositories initially using HTTP.</name> <url>http://0.0.0.0/</url> <blocked>true</blocked> </mirror>这个 mirror 的url是一个无法访问的地址http://0.0.0.0/，真正起作用的是blocked标签：一旦仓库请求匹配到这个 mirror，Maven 就不会发起任何下载，而是直接报Blocked mirror for repository: xxx。
为什么官方要加这种看起来“暴力”的拦截？原因很简单：Maven 中央仓库早已全面启用 HTTPS，但开发者完全可以在项目 POM 或自定义 settings 里把仓库地址改写成 HTTP。如果依赖在传输过程中被劫持或篡改，整个构建链都会出问题。Maven 团队为了防止“HTTPS 仓库被降级成 HTTP”这类中间人攻击，干脆把非本机的 HTTP 仓库全部拉黑。
所以这个拦截器针对的并不是你“手动配置的镜像”，而是“非本机 + HTTP 协议”的所有仓库请求。只要命中规则，就会触发 blocked 报错。
1.3 blocked 标签到底长在哪
先说清楚一个容易混淆的点：blocked不是 settings.xml 里的顶层标签，而是<mirror>节点的子标签，表示这个镜像被标记为阻塞状态。没有blocked标签的 mirror 是正常的；加了<blocked>true</blocked>的 mirror，在匹配后会阻止下载。
Maven 3.6.3 及更早版本不认识这个标签，会直接忽略它，因此旧版 Maven 加载同一份 settings.xml 不会报错。你现在用的是 3.8+，标签生效，问题就暴露了。如果你把 settings.xml 从老版本 Maven 复制到新版本 Maven，就会发现多了一个maven-default-http-blocker，这正是新版本默认配置的一部分。
2. 为什么 HTTPS 镜像没事、HTTP 私服却被拦截
2.1 mirrorOf 里 external:http:* 到底匹配了什么
很多人就算看到了maven-default-http-blocker，也不太明白external:http:*是个什么匹配规则。这里我结合自己的理解拆一下。
Maven 的mirrorOf字段支持一套表达式：
| 表达式 | 匹配范围 |
|---|---|
* | 匹配所有仓库 |
external:* | 匹配所有不在本机的仓库 |
external:http:* | 匹配所有不在本机、且使用 HTTP 协议的仓库 |
repoId | 精确匹配某个仓库 id |
*,!repoId | 匹配除了 repoId 之外的所有仓库 |
其中“不在本机”的判断标准是 host 是否为localhost、127.0.0.1或者本机回环地址。换句话说，external:http:*不会拦截http://localhost:8081/这样的本地仓库，但会拦截http://192.168.x.x、http://nexus.internal这类非本机地址。
这就是为什么你配置了阿里云镜像大概率不会报错：阿里云镜像地址是https://maven.aliyun.com/repository/public，走的是 HTTPS，不在external:http:*的匹配范围内。而你公司内网 Nexus 通常是http://192.168.10.20:8081/...，HTTP 协议加非本机地址，正好被拦个正着。
2.2 全局 settings 和用户 settings 的加载逻辑
还有一类常见情况：明明自己在 settings.xml 里配了一个内网 HTTP 仓库，为什么还会被拦？这时候要先确认 Maven 实际加载的是哪一份 settings.xml。
Maven 查找用户级配置的默认路径是~/.m2/settings.xml。如果这个文件不存在，就回退到全局配置MAVEN_HOME/conf/settings.xml。它不会自动把两份文件里的<mirrors>合并，只会二选一。也就是说：
- 如果你没有
~/.m2/settings.xml，那 Maven 加载的就是全局配置，里面包含默认的maven-default-http-blocker； - 如果你有
~/.m2/settings.xml，但没有把 blocker 节点删除或覆盖，那 Maven 加载的就是你的这份，里面可能没有 blocker； - IDEA 里如果你手动指定了 User settings file，比如填了全局路径或某个自定义文件路径，那加载的就是你指定的这个文件。
所以总有人困惑：“我明明配了内网仓库，也配了阿里云镜像，怎么还是 Blocked mirror？”原因很可能是：你以为在生效的那份 settings.xml，实际上根本不是当前构建用的那份；真正生效的全局默认文件里带着 blocker，把你的 HTTP 仓库给拦截了。
2.3 镜像匹配顺序比想象中重要
还有一个被忽略的细节：Maven 的 mirror 不是“多一个仓库源”，而是“仓库替换规则”。一旦某个 mirror 匹配到仓库请求，原仓库 URL 就会被替换成这个 mirror 的 URL，后面的 mirror 不会再参与同一个请求的匹配。
所以如果 settings.xml 里同时有多个 mirror，声明顺序决定了谁先被选中。Maven 会从头到尾遍历<mirrors>列表，选择第一个能匹配当前仓库的 mirror。这个特性既可以是坑，也可以是解药：你完全可以把一个自定义的、精确匹配内网仓库的 mirror 放在maven-default-http-blocker前面，这样请求会先命中你的 mirror，根本不会走到 blocker 那一步。
3. 三种修复方案实测：删节点、改配置、上 HTTPS
3.1 方案一：直接删除或禁用默认 blocker
如果你确定自己的内网仓库是可信的，比如公司内部私服、内网 Nexus 等，最直接的办法是去掉这个默认拦截器。操作方式有两种，任选其一：
第一种，删除整个maven-default-http-blocker节点：
<mirrors> <!-- 这里只保留你自己的 mirror 配置 --> <mirror> <id>company-nexus</id> <mirrorOf>*</mirrorOf> <url>http://192.168.10.20:8081/repository/maven-public/</url> </mirror> </mirrors>第二种，注释掉或修改它的blocked值。但这里要注意：如果你只是把<blocked>true</blocked>改成<blocked>false</blocked>，但 URL 还是http://0.0.0.0/，Maven 会尝试连接这个地址，结果依然是下载失败。所以要么整个节点删掉，要么把它改成blocked=false并且把url换成真实可达的仓库地址。
我个人更推荐直接删除节点，不要留一个无效 URL 在那里，否则以后别人看配置容易误解。
3.2 方案二：用自定义 mirror 精确覆盖并前置
有一种场景不想动全局默认配置：团队要求所有人沿用公司规定的 settings.xml 模板，这个模板里可能不允许删除 blocker，或者你想保持默认配置尽可能接近官方。这时可以把自定义 mirror 写在 blocker 前面，用精确匹配把内网仓库请求劫走。
假设你的内网仓库 id 是nexus，地址是http://192.168.10.20:8081/repository/maven-public/，配置可以写成这样：
<mirrors> <mirror> <id>nexus-http-bypass</id> <mirrorOf>nexus</mirrorOf> <url>http://192.168.10.20:8081/repository/maven-public/</url> </mirror> <mirror> <id>maven-default-http-blocker</id> <mirrorOf>external:http:*</mirrorOf> <url>http://0.0.0.0/</url> <blocked>true</blocked> </mirror> </mirrors>注意，这个自定义 mirror 的 URL 依然是 HTTP 地址，但它位于 blocker 之前。当 Maven 遇到仓库nexus时，会先命中nexus-http-bypass，然后直接走这个地址下载，根本轮不到后面的 blocker。
这种方法看起来有点“绕”，但它确实能解决“不想删默认配置”的场景。只是要记得：mirror 顺序不能写反，否则还是会被拦。如果内网仓库请求没有被精确匹配到自定义 mirror，就会落入 blocker 的匹配范围。
3.3 方案三：把 HTTP 仓库升级为 HTTPS
从安全性角度来说，最彻底的方案是让所有仓库都走 HTTPS。如果你的私服支持 HTTPS 访问，比如 Nexus 开启了 HTTPS connector，或者前面挂了反向代理做 TLS 终结，那把仓库地址改成https://nexus.internal/repository/maven-public/就行了。这样的话，external:http:*匹配不到它，不会触发 blocker。
这个方案对公共云镜像同样适用：阿里云、华为云等大厂提供的都是 HTTPS 地址，直接用就没问题。但对于自建 Nexus 或内网私服，上 HTTPS 需要证书部署和端口规划，很多小团队短期做不到，所以实际用得最多的还是方案一或方案二。
我自己的建议是：只要能上 HTTPS 就尽快上，别等依赖被劫持了再后悔。如果暂时上不了，就用方案二先保证构建可用，同时在运维侧把 HTTP 私服限定在可信内网环境。
3.4 阿里云镜像和内网私服怎么共存
国内团队经常同时需要公共仓库镜像和内网私服，比如公共组件走阿里云镜像，公司内部构件走 Nexus。有人图省事，直接写一个mirrorOf为*的阿里云镜像，结果内网私服的依赖也全部被转发到阿里云，导致私服上的私有包根本拉不到。
之前也踩过这个坑，建议这样分工：
<mirrors> <mirror> <id>aliyun-public</id> <mirrorOf>central</mirrorOf> <url>https://maven.aliyun.com/repository/public</url> </mirror> <mirror> <id>nexus</id> <mirrorOf>nexus</mirrorOf> <url>http://192.168.10.20:8081/repository/maven-public/</url> </mirror> </mirrors>这里aliyun-public只匹配central，也就是中央仓库；nexus只匹配仓库 id 为nexus的私有仓库。这样公共依赖走阿里云，私有依赖走内网。如果你不想为内网仓库单独配置，而是所有非中央仓库都走公司私服，也可以用*,!central这样的排除语法，但可读性会差一些，我倾向于写明确。
4. 从报错到定位：一条完整的 settings.xml 排查链路
4.1 三步确认实际生效的 Maven 配置
遇到 Blocked mirror 报错，先别急着改配置，按下面三步确认环境：
第一步，确认当前使用的 Maven 版本：
mvn -v如果输出里显示 3.8.0 及以上，就可能触发 blocked 拦截逻辑。如果你在命令行用 3.6.3、但在 IDEA 里用内置 3.9.x，那么两边行为不一致，这一点非常迷惑人。
第二步，查看当前生效的 settings.xml：
mvn help:effective-settings这个命令会打印出经过解析后真正生效的完整 settings 配置，重点看<mirrors>部分。如果里面有maven-default-http-blocker，那基本可以确定它拦了你的 HTTP 仓库。
第三步，确认当前项目声明的仓库地址。可以看 pom.xml 里的<repositories>标签，也可以用：
mvn help:effective-pom确定仓库 id 和 URL 后，和mirrorOf的匹配规则对照，判断它是否命中external:http:*。
4.2 命令行复现与验证
有时候构建报错信息里混着其他问题，为了快速复现，可以用dependency:get单独拉一个依赖来测试：
mvn dependency:get \ -Dartifact=com.example:lib:1.0 \ -DremoteRepositories=http://192.168.10.20:8081/repository/maven-public/如果输出里出现Blocked mirror，说明只要请求这个 HTTP 仓库就会中招。改完 settings.xml 后再跑一次同样的命令，如果依赖能正常拉到本地仓库~/.m2/repository，那就说明修复生效了。
这里提醒一句：命令里的remoteRepositories参数只用于临时指定远程仓库，它不会影响你 settings.xml 里的 mirror 配置，所以很适合用来做“最小化复现实验”。
4.3 IDEA 和 CI 场景下的隐藏坑
IDEA 场景下，最经典的坑是“命令行没问题，IDEA 里报错”。原因通常是 IDEA 使用的是它自带或另外配置的 Maven 版本，而不是你在终端里配的那一个。打开Settings -> Build, Execution, Deployment -> Build Tools -> Maven，查看：
- Maven home path
- User settings file
- Local repository
如果User settings file指向的是全局目录下的conf/settings.xml，那你实际用的就是带 blocker 的默认配置。建议把团队统一的 settings.xml 放到~/.m2/settings.xml，并在 IDEA 里明确选这个文件。
CI 场景下则往往是另一个问题：基础镜像内置了 Maven 3.8+，但构建脚本没有把自定义 settings.xml 传进去，流水线用的是镜像自带的全局配置，导致内网 HTTP 仓库被拦。解决方式是在 CI 命令里显式指定：
mvn -s path/to/settings.xml clean package如果不确定流水线用的 settings 是哪一份，可以在流水线脚本里加一步mvn help:effective-settings打印出来看。
5. 避坑清单与常见问题速查表
5.1 我在 localhost 部署的私服为什么没事
前面提过，external:http:*里的 external 会排除本机地址。如果你把私服地址配成http://localhost:8081/或者http://127.0.0.1:8081/，Maven 会认为这不是“外部队列”，所以不会拦截。很多人开发机上用本地 Nexus 没碰到问题，一到测试环境换成内网 IP 就立刻报 Blocked mirror，原因就在这里。
这算一个合法的“逃生通道”，但我不建议你把测试环境私服地址改成 localhost 来绕过，太脆弱了。开发机本地可以这么用，团队协作环境还是走正儿八经的 mirror 配置。
5.2 删了 blocker 还报错
如果你已经删除了maven-default-http-blocker节点，但还是看到 Blocked mirror，那大概率是这份改过的 settings.xml 根本没生效。常见原因有三个：
- 改的是全局配置，但 Maven 实际加载的是
~/.m2/settings.xml； - 改的是某个自定义文件，但 IDEA 里 User settings file 指向的是另一个文件；
- CI 里用
-s参数指定了别的位置的文件。
排查方法还是回到 4.1 节：用mvn help:effective-settings看最终生效的配置，不要凭猜测去改文件。
另外一个少见但确实存在的情况：项目本身在.mvn/maven.config或.mvn/maven.properties里指定了-s路径，导致命令行和 IDE 读到的 settings 不一样。如果项目根目录有.mvn目录，打开看看里面有没有这类配置。
5.3 其他容易混淆的点
关于blocked标签的文案，网上讨论经常说“settings.xml 里的 blocked 标签”，严格来说它其实是<mirror>的子标签，只在 3.8+ 生效。还有一点：报错信息里的仓库 id 是 repository id，不是 mirror id，所以别在<mirrors>里找同名节点。
如果把<blocked>值改成false后仍然访问了http://0.0.0.0/这种地址，那说明你只改了标签、没改 URL，这个也要注意。
5.4 常见问题速查表
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
| 内网 HTTP 仓库全部报 Blocked mirror | 默认 blocker 生效 | 删除 blocker，或自定义 mirror 前置 |
| 配置了阿里云镜像还报 Blocked mirror | 实际生效的 settings 不是你以为的那份 | 用mvn help:effective-settings确认 |
| localhost 私服正常，换内网 IP 报错 | external:http:*排除本机地址 | 使用本机地址，或正经配置 mirror |
| 删掉 blocker 后仍下载失败 | settings 文件没被加载 | 检查~/.m2/settings.xml和 IDEA 设置 |
只配mirrorOf *阿里云后私服依赖消失 | 所有仓库被转发到阿里云 | 改用central或*,!nexus |
| 命令行正常，IDEA 里报错 | IDEA 使用内置 Maven 和另一个 settings | 统一 Maven home 与 user settings |
这次排查给我最深的印象是：Maven 的报错信息有时候看着很吓人，但只要你把“实际加载了哪个 settings.xml”和“mirrorOf 匹配规则”这两件事想清楚，几乎所有 Blocked mirror 问题都能在十分钟内定位。如果你刚升级 Maven 版本，建议顺手跑一遍mvn help:effective-settings，确认哪些仓库正在走 HTTP、哪些仓库会被默认拦截，把隐患提前解决掉，而不是等构建挂了再回来翻日志。
