Maven插件下载失败？三步解决SSL握手错误与镜像配置
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官方文档）。