Java Module 为何报错

Java Module（即 Java 9 引入的 JPMS，Java Platform Module System）报错的原因非常多，一般不是“Java Module 本身错了”，而是模块声明、依赖、访问权限或构建配置有问题。我给你一个体系化的排查清单 + 常见错误示例，你可以对照看看。

一、最常见原因速查表

二、典型错误示例与解决方案

1️⃣ Module not found

报错示例

Error: Module com.example.util not found

module-info.java

module app {
    requires com.example.util;
}

原因

• com.example.util 不存在
• 依赖的 jar 没被当模块处理
• 非模块 jar 被当成「未命名模块」

✅ 解决

• 确认 jar 是否是模块（是否有 module-info.class）
• 或改成依赖 自动模块名

module app {
    requires util; // 自动模块名
}

2️⃣ Package not visible（最容易踩坑）

报错

com.example.util.Hello is not visible

工具模块

module util {
    // 没有 exports
}

✅ 解决

module util {
    exports com.example.util;
}

⚠️ 规则

• 不 exports → 其他模块根本看不到这个包
• 即使 requires 了也没用

3️⃣ 反射访问失败（JSON / ORM 最常见）

报错

InaccessibleObjectException

原因

• 框架用反射访问私有成员
• 模块没放开

✅ 解决

module util {
    opens com.example.util;
}

或（深度反射）

opens com.example.util to jackson.databind;

4️⃣ 循环依赖

错误

Cycle detected

module a {
    requires b;
}
module b {
    requires a;
}

✅ 解决

• 拆分公共模块
• 用接口解耦

5️⃣ Java 8 项目写 module-info.java

❌ 不支持

module-info.java is not supported in -source 8

✅ 解决

• 至少用 Java 11+
• 或删除 module-info.java

6️⃣ Maven / Gradle 构建失败

Maven 常见错误

module not found: xxx

✅ 注意

• module-info.java 默认在 src/main/java
• Maven 3.9+ 才对模块支持较完整
• 依赖必须是 named module 或自动模块

三、快速自检清单 ✅

你可以逐条检查：

• [ ] JDK ≥ 11
• [ ] module-info.java 文件存在
• [ ] requires 的模块名真实存在
• [ ] 被依赖模块 exports 了包
• [ ] 反射访问是否 opens
• [ ] 没有循环依赖
• [ ] 构建工具版本支持模块

四、如果你愿意，我可以直接帮你定位

你可以直接贴出：

1. 完整报错信息
2. module-info.java
3. 使用的 JDK 版本
4. Maven / Gradle 配置
5. 是哪种依赖（自己模块 / 第三方 jar）

我可以直接告诉你 是哪一条规则被违反了 ✅