本文系统讲解 spring boot 项目中 pom.xml 添加依赖的规范方法，涵盖官方 starter 依赖、本地 jar 依赖、模块间依赖及常见错误排查，助你避免“missing artifact”等典型问题。
本文系统讲解 spring boot 项目中 pom.xml 添加依赖的规范方法，涵盖官方 starter 依赖、本地 jar 依赖、模块间依赖及常见错误排查，助你避免“missing artifact”等典型问题。
在 Spring Boot 项目开发中，pom.xml 是 Maven 构建的核心配置文件，其依赖管理直接影响项目能否正常编译、运行与打包。许多开发者初遇“Missing artifact”（如 org.apache.tomcat.embed:tomcat.embed.jasper:jar:10.1.3）报错，根源往往并非配置语法错误，而是版本不匹配、坐标不准确或依赖策略未对齐 Spring Boot 版本约束。以下为权威、可落地的实践指南。
✅ 一、优先使用 Spring Boot 官方 Starter（推荐方式）
Spring Boot 通过 spring-boot-starter-parent 统一管理依赖版本，因此绝大多数场景下无需手动指定
<parent><groupid>org.springframework.boot</groupid><artifactid>spring-boot-starter-parent</artifactid><version>3.2.12</version><!-- 建议使用最新稳定版（截至2026年11月） --><relativepath></relativepath></parent>
在此基础上，添加 Web 支持只需简洁声明：
<dependencies><!-- 内置 Tomcat + Spring MVC 自动配置 --><dependency><groupid>org.springframework.boot</groupid><artifactid>spring-boot-starter-web</artifactid></dependency><!-- 若需 JSP 支持（仅限 WAR 部署），才需额外引入 Jasper --><dependency><groupid>org.apache.tomcat.embed</groupid><artifactid>tomcat-embed-jasper</artifactid><scope>provided</scope><!-- 注意：artifactId 是 tomcat-embed-jasper，非 tomcat.embed.jasper --><!-- 版本由 spring-boot-dependencies 自动匹配，无需显式写 --></dependency></dependencies>
? 关键提示：
tomcat-embed-jasper的 artifactId 是连字符格式（tomcat-embed-jasper），而非点分格式（tomcat.embed.jasper）；且其版本必须与当前 Spring Boot 内嵌 Tomcat 版本严格兼容。例如 Spring Boot 3.2.x 默认绑定 Tomcat 10.1.x，但Maven Central 中tomcat-embed-jasper10.1.3 并不存在（如提问中所查），实际可用版本为10.1.29（对应 Spring Boot 3.2.12）。直接删除让父 POM 自动注入，是最安全做法。
✅ 二、添加本地 JAR 依赖（离线/私有组件）
当依赖无法从中央仓库获取（如国产数据库驱动、内部 SDK），需使用 system scope 并显式指定路径：
<dependency><groupid>com.kingbase8</groupid><artifactid>kingbase8</artifactid><version>8.2.0</version><scope>system</scope><systempath>${project.basedir}/lib/kingbase8-8.2.0.jar</systempath></dependency>
⚠️ 重要补充（否则打包失败）：
Spring Boot 默认的 spring-boot-maven-plugin 不会将 system 依赖打入 BOOT-INF/lib/，必须在
<build><plugins><plugin><groupid>org.springframework.boot</groupid><artifactid>spring-boot-maven-plugin</artifactid></plugin></plugins><resources><resource><directory>${project.basedir}/lib</directory><targetpath>BOOT-INF/lib/</targetpath><includes><include>**/*.jar</include></includes></resource></resources></build>
✅ 三、模块化项目添加本地模块依赖（Multi-module）
若项目含多个子模块（如 module-core, module-api），需同时完成两步，缺一不可：
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
-
在
pom.xml中声明模块依赖（注意groupId/artifactId/version必须与被引用模块的pom.xml一致）：<dependency><groupid>com.example</groupid><artifactid>module-core</artifactid><version>0.0.1-SNAPSHOT</version></dependency>
-
在 IDEA 中显式添加模块依赖：
File → Project Structure → Modules → Dependencies → '+' → Module Dependency → 选择对应模块? 此步确保 IDE 编译器识别源码级引用，避免“cannot resolve symbol”。
⚠️ 四、高频错误与避坑清单
| 问题现象 | 根本原因 | 解决方案 |
|---|---|---|
Missing artifact xxx:yyy:jar:zzz |
版本号不存在于 Maven Central / 仓库地址错误 / artifactId 拼写错误 | 使用 mvnrepository.com 精确搜索，确认坐标与版本；删除 |
依赖生效但运行时报 ClassNotFoundException
|
system 依赖未配置 resources 复制规则 |
补全 BOOT-INF/lib/
|
| 多模块项目编译通过但启动失败 | 仅配置了 pom.xml 依赖，未在 IDEA 中添加模块依赖 |
同时执行 Maven 依赖声明 + IDEA 模块依赖配置 |
| Lombok 注解不生效 | 未启用 Annotation Processing 或未添加 optional=true
|
在 pom.xml 中添加 Lombok 依赖，并在 IDEA 中开启 Enable annotation processing
|
✅ 总结
Spring Boot 的依赖管理是“约定优于配置”的典范：
? 首选 starter —— 利用 spring-boot-starter-parent 的 dependencyManagement 自动收敛版本；
? 慎用 system scope —— 必须配合
? 模块依赖双保险 —— pom.xml 声明 + IDE 显式关联；
? 验证先于编码 —— 任何新依赖，务必通过 mvnrepository.com 核实坐标有效性。
遵循以上规范，即可彻底规避 Missing artifact、类加载失败、IDE 无法识别等典型工程化问题，让依赖管理真正成为提效利器，而非阻塞瓶颈。
