Java 模块路径和类路径冲突的定位清单

Java 项目同时使用 module-path 和 classpath 时，最容易出现的误判是“把依赖再加一遍就能找到类”。更可靠的定位顺序是：先确认依赖是什么形态，再确认编译和启动各自使用了哪条路径，最后检查模块声明是否允许访问。

官方地址：https://docs.oracle.com/en/java/javase/26/docs/specs/man/javac.html

先判断两条路径承载的对象

classpath 面向包层级：目录里按 com/example/App.class 这样的包路径组织，普通 JAR 也属于这一类。它适合还没有模块声明的旧依赖。module-path 面向模块层级：一个模块目录或模块化 JAR 中应能识别出 module-info.class；带有模块声明的库需要按模块图解析。

自动模块是过渡形态：一个没有 module-info.class 的 JAR 被放到模块路径后，启动器可以根据 JAR 名称推导模块名，但这不等于它已经拥有清晰的模块 API。排障时先列出依赖文件，给每个依赖标记“普通 JAR、自动模块还是命名模块”，不要只看文件名。

按编译与启动命令复现冲突

把问题缩小到一个入口模块和一个依赖。编译模块化代码时，模块依赖放到 --module-path，仍未模块化的第三方 JAR 可以放到 --class-path。启动时也要保持同样的边界；编译命令里出现过的路径不会自动替你带入下一次 java 调用。

# 编译模块源码：模块依赖与旧式 JAR 分开声明
javac --module-path mods --class-path 'lib/*' -d out \
  --module-source-path 'src/*' -m app

# 启动同一个入口模块：重复声明运行时真正需要的两条路径
java --module-path out:mods --class-path 'lib/*' \
  -m app/com.example.app.Main

如果报“找不到模块”，先看模块路径是否指向模块目录的父目录，而不是随手指向一个普通 JAR。若报“找不到类”，再确认该类来自 classpath 还是 module-path。若出现重复类，则说明同一坐标同时从两条路径可见，应删除其中一份或统一依赖形态。

定位 requires、exports 与可见性

入口模块必须在 module-info.java 中声明它真正依赖的命名模块，例如 requires com.example.codec;。被依赖模块还要把需要给外部使用的包导出：

module app {
    // 声明编译期和运行期都需要解析的模块
    requires com.example.codec;
}

module com.example.codec {
    // 只开放 API 包，内部实现包仍保持模块边界
    exports com.example.codec.api;
}

requires 缺失时，模块图无法解析依赖；exports 缺失时，模块可能已经解析成功，但访问具体包会被拒绝。不要用 --add-exports 作为默认修复，它更适合临时迁移或诊断；长期方案是修正模块声明和依赖边界。

用四项清单收敛部署配置

1. 看对象：确认每个 JAR 是否含模块描述，普通 JAR 不要因为“看起来像模块”就放入模块图。
2. 看入口：确认 -m 模块名/主类 与入口模块声明一致；非模块化应用则继续使用类路径入口。
3. 看边界：对照 requires、exports 和实际导入包，区分“未解析”与“不可访问”。
4. 看一致性：对比编译、测试和部署脚本，确保输出目录、依赖版本没有同时出现在两条路径。

常见问题

classpath 和 module-path 可以同时使用吗？

可以，兼容旧 JAR 时很常见，但要清楚每个依赖只由一条路径负责，避免同一个类被两边同时提供。

为什么编译成功，启动仍然报不可访问？

编译与启动可能使用了不同的路径或入口模块，也可能编译阶段使用了临时开放参数。先逐项对照两条命令，再检查 exports。