Maven插件下载失败？三步解决SSL握手错误与镜像配置-CSDN博客

本文链接：https://blog.csdn.net/JakeMa1024/article/details/147502211

Maven插件下载失败？三步解决SSL握手错误与镜像配置

引言

在使用Maven构建Java项目时，你是否遇到过类似以下错误？

[ERROR] Plugin org.apache.maven.plugins:maven-jar-plugin:3.1.1 or one of its dependencies could not be resolved: Failed to read artifact descriptor for org.apache.maven.plugins:maven-jar-plugin:jar:3.1.1: The following artifacts could not be resolved: org.apache.maven.plugins:maven-jar-plugin:pom:3.1.1 (absent): Could not transfer artifact org.apache.maven.plugins:maven-jar-plugin:pom:3.1.1 from/to central (https://repo.maven.apache.org/maven2): Remote host terminated the handshake: SSL peer shut down incorrectly -> [Help 1]

这个错误通常与网络连接、SSL证书或仓库配置有关。本文将通过一个真实案例，手把手教你如何快速解决此类问题。

问题分析

错误信息中的关键点：

插件无法下载：Maven无法从中央仓库（https://repo.maven.apache.org/maven2）获取maven-jar-plugin插件。
SSL握手失败：错误提示SSL peer shut down incorrectly，说明SSL/TLS协议版本不兼容或网络问题。

常见原因：

网络限制：国内用户可能因网络政策无法直接访问Maven中央仓库。
SSL/TLS版本过低：旧版本Java或Maven可能使用不兼容的SSL协议（如TLS 1.0）。
本地缓存损坏：Maven缓存文件可能被污染，导致插件无法正确下载。

解决方案：配置国内Maven镜像

通过将Maven的中央仓库地址替换为国内镜像，可以快速解决问题。以下是具体步骤：

步骤1：找到Maven配置文件

Maven的全局配置文件是settings.xml，路径如下：

Linux/macOS：~/.m2/settings.xml
Windows：C:\Users\<你的用户名>\.m2\settings.xml

如果文件不存在，直接创建即可。

步骤2：添加国内镜像配置

在settings.xml中添加以下内容，配置阿里云或华为云的Maven镜像：

<settings>
    <!-- 其他配置... -->
    <mirrors>
        <!-- 阿里云镜像（推荐） -->
        <mirror>
            <id>aliyun</id>
            <name>Aliyun Maven</name>
            <url>https://maven.aliyun.com/repository/public</url>
            <mirrorOf>central</mirrorOf>
        </mirror>
        <!-- 华为云镜像 -->
        <mirror>
            <id>huaweicloud</id>
            <name>Huawei Maven</name>
            <url>https://repo.huaweicloud.com/maven</url>
            <mirrorOf>central</mirrorOf>
        </mirror>
    </mirrors>
</settings>

解释：
- <mirrorOf>central</mirrorOf> 表示将Maven中央仓库的请求重定向到指定镜像。
- 阿里云和华为云镜像均支持国内高速访问，选择其中一个即可。

步骤3：验证配置生效

保存settings.xml后，重新运行Maven命令（如mvn clean install）。
如果成功，你会看到类似以下日志：

[INFO] Downloading from aliyun: https://maven.aliyun.com/repository/public/org/apache/maven/plugins/maven-jar-plugin/3.1.1/maven-jar-plugin-3.1.1.pom
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS

扩展建议

如果上述方法未解决问题，可尝试以下补充方案：

1. 强制使用TLS 1.2协议

在运行Maven时，通过JVM参数指定TLS版本：

# Linux/macOS
MAVEN_OPTS="-Dhttps.protocols=TLSv1.2" mvn clean install

# Windows
set MAVEN_OPTS="-Dhttps.protocols=TLSv1.2" && mvn clean install

2. 清理本地Maven缓存

删除本地仓库中损坏的插件目录：

rm -rf ~/.m2/repository/org/apache/maven/plugins/maven-jar-plugin

3. 检查Java版本

确保Java版本≥8（推荐使用Java 11+）：

java -version

总结

通过配置国内Maven镜像，可以轻松解决因网络或SSL协议导致的插件下载失败问题。本文的步骤简单且通用，适用于大多数Maven相关网络问题。如果遇到其他类似错误，不妨尝试以下思路：

优先配置镜像：国内用户首选阿里云或华为云镜像。
检查SSL/TLS版本：强制使用TLS 1.2。
清理缓存与升级工具：确保Maven和Java版本最新。

附录：常见问题

Q：修改settings.xml后，如何确认镜像生效？
A：在Maven日志中查看下载源是否为镜像地址（如https://maven.aliyun.com）。

Q：是否需要同时配置多个镜像？
A：只需选择一个即可，多个镜像可能冲突。

Q：公司网络有代理怎么办？
A：在settings.xml中添加代理配置（参考Maven官方文档）。