sts 更新 maven 项目时因 mapstruct 依赖卡在 75% 无响应，通常是本地 maven 仓库中 mapstruct 相关构件损坏所致；删除对应版本缓存后重试即可恢复。
在 Spring Tool Suite（STS）中集成 MapStruct 时，部分开发者会遇到 Maven 项目更新长期停滞（如显示“Updating Maven Project: (75%)”并持续数小时），尤其在添加 mapstruct 和 mapstruct-processor 依赖后。该问题并非 MapStruct 本身缺陷或版本兼容性问题，而是 STS 在解析依赖元数据或下载构件过程中，因本地 Maven 仓库（.m2/repository）中已存在不完整、损坏或校验失败的 MapStruct 缓存文件，导致解析器陷入死循环或无限重试。
✅ 根本原因与推荐解决方案
最常见且高效的解决方式是清理本地 Maven 仓库中 MapStruct 的相关缓存：
定位本地 Maven 仓库路径（默认为 ~/.m2/repository/，Windows 下通常为 %USERPROFILE%\.m2\repository\）；
-
删除以下路径（以 1.5.2.Final 为例，按你实际使用的版本调整）：
~/.m2/repository/org/mapstruct/mapstruct/1.5.2.Final/ ~/.m2/repository/org/mapstruct/mapstruct-processor/1.5.2.Final/ ~/.m2/repository/org/mapstruct/mapstruct-parent/1.5.2.Final/
? 提示：也可直接删除整个 org/mapstruct/ 目录，Maven 会在下次构建时自动重新下载完整、干净的构件。
在 STS 中右键项目 → Maven → Update Project…（勾选 Force Update of Snapshots/Releases），点击 OK。
⚙️ 配置优化建议（避免复发）
确保 pom.xml 中 MapStruct 的声明符合最佳实践（尤其注意 Java 版本一致性）：
<properties>
<java.version>11</java.version>
<org.mapstruct.version>1.5.2.Final</org.mapstruct.version>
</properties>
<dependencies>
<!-- 运行时依赖（仅需 mapstruct，无需 processor） -->
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>${org.mapstruct.version}</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>11</source> <!-- 必须与 java.version 一致 -->
<target>11</target>
<annotationProcessorPaths>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>${org.mapstruct.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>⚠️ 注意事项：
- mapstruct-processor 仅需配置在 maven-compiler-plugin 的 annotationProcessorPaths 中，不可作为
声明在 下（否则可能触发重复处理或 IDE 解析异常）； - 确保
和 与 严格匹配（本例均为 11），避免编译插件与 JDK 版本错配； - 若使用较新 Spring Boot（如 3.x），请升级至 MapStruct 1.6+ 并适配 Jakarta EE 命名空间。
✅ 验证是否修复
清理缓存并强制更新后：
- STS 底部状态栏应正常完成更新（不再卡住）；
- target/generated-sources/annotations/ 下应生成 .java 映射实现类；
- 编译和运行均无 Mapper not found 或 No implementation was created 错误。
通过以上步骤，90% 以上的 STS + MapStruct 卡顿问题可立即解决。若仍复现，建议检查企业级 Nexus/Artifactory 代理配置、网络 DNS 解析稳定性，或临时切换为官方 Maven Central 镜像验证。
