MapStruct Maven 依赖卡在 STS 中更新失败的解决方案

聖光之護 2026-01-26 00:00:00 次阅读

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 版本一致性）：


    11
    1.5.2.Final



    
    
        org.mapstruct
        mapstruct
        ${org.mapstruct.version}
    



    
        
            org.apache.maven.plugins
            maven-compiler-plugin
            3.8.1
            
                11  
                11
                
                    
                        org.mapstruct
                        mapstruct-processor
                        ${org.mapstruct.version}

⚠️ 注意事项：

mapstruct-processor 仅需配置在 maven-compiler-plugin 的 annotationProcessorPaths 中，不可作为声明在下（否则可能触发重复处理或 IDE 解析异常）；
确保和与 java.version> 严格匹配（本例均为 11），避免编译插件与 JDK 版
本错配；
若使用较新 Spring Boot（如 3.x），请升级至 MapStruct 1.6+ 并适配 Jakarta EE 命名空间。