最常见原因是依赖作用域（scope）设置错误，如误用test或provided导致运行时不可见；应确保生产代码使用compile（默认）或runtime，避免system scope，用mvn install:install-file安装本地JAR，并通过dependency:tree排查版本冲突。
为什么 pom.xml 里加了依赖却报 ClassNotFoundException
最常见原因不是没写依赖，而是作用域（scope）设错了。比如误用 test 或 provided，导致运行时不可见。
检查点：
-
compile（默认）适用于编译、测试、运行全阶段；生产代码必须用这个或不写scope -
runtime适合 JDBC 驱动这类只在运行时需要的包，但编译期不能引用其类 -
test只对src/test/java生效，主程序里 import 就会编译失败 - Maven 默认不会把
provided依赖打进jar，但 Tomcat 等容器会提供，本地运行 main 方法时容易直接抛异常
如何让 Maven 正确加载本地 JAR（非 Maven 仓库的依赖）
别用 system scope —— 它已弃用，且会导致 CI 构建失败、IDE 同步异常、无法上传到私有仓库。
推荐做法：
立即学习“Java免费学习笔记（深入）”；
- 用
mvn install:install-file命令把 JAR 安装进本地仓库：mvn install:install-file -Dfile=lib/xxx-sdk-1.2.0.jar -DgroupId=com.example -DartifactId=xxx-sdk -Dversion=1.2.0 -Dpackaging=jar
- 然后像普通依赖一样写进
pom.xml：<dependency><br> <groupId>com.example</groupId><br> <artifactId>xxx-sdk</artifactId><br> <version>1.2.0</version><br></dependency>
- 如果团队协作，建议同步推送到 Nexus/Artifactory 私服，而非每人本地 install
使用 mvn dependency:tree 排查冲突依赖的实际生效版本
当两个依赖都引入了不同版本的 guava，Maven 默认按「最近路径优先」选一个，但你未必知道哪个胜出了。
执行命令：
mvn dependency:tree -Dincludes=com.google.guava:guava
关键看输出中的 omitted for duplicate 和 omitted for conflict 标记：
- 带
compile的那行是最终被采纳的版本 - 其他被省略的，说明已被排除 —— 这时若发现业务代码调用了被排除版本里的新 API，就会
NoSuchMethodError - 想强制指定版本？在
pom.xml的<dependencymanagement></dependencymanagement>中声明<version></version>即可统一，无需每个子模块重复写
Gradle 用户误用 implementation 替代 api 导致下游模块编译失败
这是 Gradle 5+ 的经典陷阱：如果 A 模块用 implementation 引入了 gson，又在自己的 public API（比如返回 Gson 类型的方法）中暴露了它，那么依赖 A 的 B 模块编译时会找不到 Gson 类。
修复逻辑：
- 仅内部使用的依赖（如测试工具、日志实现）→ 用
implementation - 会被本模块 public API 直接引用的类型 → 必须用
api（等价于旧版compile） - 不确定？先用
api，再根据实际依赖传递范围收紧 - 检查方式：在 B 模块里尝试 import A 暴露的类，如果 IDE 报红或编译失败，大概率是 A 用了错的作用域
mvn dependency:tree 或 ./gradlew dependencies 多跑一次就能提前发现。 
