前两天帮同事排查一个Spring Boot多模块项目mvn clean install跑到一半突然报错内容很直接——某个子模块的源码目录未创建后面跟着一串“程序包不存在”的异常。这种报错在 Maven 多模块项目里其实挺常见但它有个迷惑性第一眼看上去像代码写错了再看又以为是 Maven 没建目录最后折腾下来才发现问题往往出在“构建环境与目录约定”之间的配合上。花了一下午把它解决掉加上之前帮群里朋友看过的几次类似问题今天把完整的排查思路和操作步骤整理出来。如果你也遇到过“目录未创建”“源码目录缺失”“子模块引不到类”这类怪毛病这篇应该能帮你少走不少弯路。1. 多模块项目为什么会报“目录未创建”聚合与继承的底层逻辑1.1 聚合模块、父级 POM 和子模块三者的关系很多刚接触 Maven 多模块的人会把“聚合”和“继承”混在一起。其实 Maven 做多模块有两种机制一种是父 POM 通过modules把子模块聚合起来让所有子模块能一次构建另一种是子模块通过parent继承父 POM 的依赖和插件配置。实际项目里通常会同时用所以你会看到根目录那个 pom.xml 既写了packagingpom/packaging又声明了一堆module。一个典型的结构长这样groupIdcom.example/groupId artifactIdcloud-parent/artifactId version1.0.0/version packagingpom/packaging modules modulecloud-common/module modulecloud-app/module modulecloud-web/module /modules子模块里再通过parent指回父 POM。构建时只要在根目录执行mvn clean installMaven 就会按照模块声明顺序依次构建并且把每个模块打成 jar 安装到本地仓库供后续模块引用。关键点来了既然构建是按顺序来的那么任何一个模块如果没有正常的源码目录结构就会在编译阶段直接断片。断片之后后面所有依赖它的模块都会跟着报错。所以“目录未创建”看起来是个局部小问题实际上影响的是整条构建链路。1.2 “约定优于配置”到底约定了哪些目录Maven 之所以叫构建工具而不是脚本工具核心就是它把大部分规则固定下来了你不需要告诉它源码放哪、资源放哪、测试放哪。它默认有一套标准源码目录${basedir}/src/main/java资源目录${basedir}/src/main/resources测试源码目录${basedir}/src/test/java测试资源目录${basedir}/src/test/resources编译输出目录${basedir}/target/classes打包输出目录${basedir}/target这套约定让所有 Maven 项目看起来都是一个模子换团队、换电脑、换 CI 服务器成本都很低。但也正因为是约定Maven 不会像某些 IDE 那样“贴心”地替你创建这些目录。目录缺失时它只会干巴巴地报一句找不到目录或者找不到符号然后退出构建。很多新手在这里就被绕进去了总觉得 Maven 应该自动把所有标准目录生成好于是盯着mvn archetype:generate找答案。其实用 archetype 确实能生成完整骨架但更多时候你是在已有工程里手动加了一个子模块忘记补目录结构这才是“目录未创建”的高发场景。1.3 目录缺少对构建链路的影响面单模块工程缺个src/main/java后果相对简单要么编译输出为空要么直接构建失败。多模块工程就不一样了它对目录结构的依赖是整个链条式的。举个例子cloud-web依赖cloud-common里的一个工具类。构建时 Maven 会去本地仓库找cloud-common-1.0.0.jar找到之后才能编译 web 模块。如果cloud-common模块自己就缺源码目录它打出来的 jar 就是空的甚至根本打不出来。这时候 web 模块的报错会是“找不到com.example.common.util”之类的程序包不存在而不是直接说目录没建。所以你会看到一种很奇怪的现象整条报错里最显眼的是“程序包不存在”但真正的病根在另一个模块的目录结构上。反过来说如果你在本地 IDE 里能正常跑因为 IDE 有自动编译和索引机制结果命令行构建就挂了那更要先怀疑目录结构而不是代码本身。2. 动手前先搞懂Maven 在编译时到底需要“找到”哪些目录2.1 Java 编译器的视角源码目录与 classpath要彻底搞明白这个问题得站在 javac 的角度看一次编译过程。Maven 调用编译器时会做两件事第一把当前模块src/main/java下的所有.java文件编译成.class文件输出到target/classes第二把当前模块依赖的 jar 包路径拼进 classpath让 javac 能解析到其他模块或第三方库的类。对 javac 来说它拿到的是一个文件路径列表。src/main/java这个路径如果不存在就相当于一个空的输入集合编译出来的结果自然也是空的。而“依赖的 jar 包不存在”换个角度看也等于 classpath 里某个目录或文件缺失。所以你会发现Maven 报错时经常把“目录未创建”“程序包不存在”“找不到符号”混在一起因为它们本质上是同一类问题——编译器要访问的东西不在它预期的位置上。这次我排查的工程报错信息先是“源码目录不存在”后续模块又跟着报“程序包不存在”两种现象同时出现基本可以锁定是前面某个模块没有正常产出 jar而不是业务代码本身有语法问题。2.2 三种“目录未创建”的真实形态同样的报错根因可能完全不同。根据我遇到过的案例大致可以分成三种形态典型现象判断方法解决方向物理目录缺失某个子模块完全没有src/main/javaGit 克隆后目录不存在用文件管理器或 tree 命令查看模块目录结构手动创建标准源码目录或重新用 Maven 骨架生成模块仓库 jar 缺失mvn clean之后没执行install后续模块引用不到前序模块的类查看本地仓库~/.m2/repository下对应模块路径是否真的有 jar在父 POM 根目录执行完整mvn install按依赖顺序安装模块构建上下文错乱IDE 识别不了 Maven 模块或者子模块没有parent关联构建时被当成独立工程打开 IDE 的 Maven 面板看是否列出全部模块检查 pom 引用关系让 IDE 重新导入或关联 Maven 项目修正 parent/modules 配置这三种形态往往会叠加。比如物理目录缺失导致模块 install 出来的 jar 是空的接着引发“程序包不存在”。排查时不要只盯第一行报错要把整个构建日志从头到尾看一遍。2.3 排查前置条件版本、仓库与 settings.xml 配置在开始处理目录问题之前我建议先确认一轮基础环境。这一步看着多余实际上能过滤掉大量干扰项。先跑mvn -v看版本和 Java 版本。Maven 的版本选择不用太纠结3.8.x 和 3.9.x 都是当前主流版本。网上有些标题写着“maven 3.88 下载”的其实官网并没有这个版本号大概率是 3.8.8 的误传下载时认准官方路径就行。如果是在 Windows 7 这类老系统上装尽量选较新的 3.8.x 版本同时确认JAVA_HOME指向的 JDK 版本和项目编译目标一致避免老环境里出现 JDK 类库找不到的问题。然后确认本地仓库位置。默认是~/.m2/repository但很多公司会统一改到自定义目录靠settings.xml里的localRepository指定。如果配了阿里云镜像或者其他私服还要确认 jar 包的下载路径是否和当前使用的settings.xml对应。经常有人本地明明有某个 jar项目里却一直报找不到就是因为 IDE 里配置的 Maven 仓库路径和命令行用的不是同一个。顺手贴一个常用的国内镜像配置能解决大部分依赖下载慢和下载失败的问题mirrors mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors不要贪多一次配一个主镜像就够了。配置多个镜像有时反而会在依赖解析时引入不确定因素尤其是在多模块项目里某个模块先去错误的仓库找依赖构建速度会拖慢很久报错也五花八门。3. 完整排查流程从报错日志到目录修复再到构建通过3.1 复现场景cloud-parent 多模块工程案例为了把过程讲清楚我构造一个和当时几乎一样的工程示例。父模块叫cloud-parent下面挂了三个子模块cloud-parent ├── pom.xml ├── cloud-common │ └── pom.xml ├── cloud-app │ ├── pom.xml │ └── src/main/java/com/example/app/AppApplication.java └── cloud-web ├── pom.xml └── src/main/java/com/example/web/WebApplication.java出问题的模块是cloud-common。它的 pom.xml 基本是复制父 POM 里的配置但目录结构里只有pom.xml没有src/main/java。也就是说这个模块现在是一个“空心”模块。我在根目录执行mvn clean install后cloud-common模块本身可能不会立刻报错因为空模块在 Maven 眼里也算一个合法模块它会生成一个不含 class 的 jar。真正崩掉的是下一个环节——cloud-app编译时找不到cloud-common里的类。日志里的关键错误长这样[ERROR] /path/to/cloud-app/src/main/java/com/example/app/AppApplication.java:[4,17] 程序包com.example.common.util不存在 [ERROR] /path/to/cloud-app/src/main/java/com/example/app/AppApplication.java:[8,34] 找不到符号这种报错非常容易让人误判成代码里依赖写错或者 jar 没下下来。但把cloud-common的src目录加回来之后整个构建立刻恢复。说白了这个模块从一开始就没有源码自然也就无法提供任何类给下游模块。3.2 分步定位先判断是哪一种“目录缺失”遇到报错先别慌按下面几步快速定位。第一步看构建日志里报错所属的模块是哪一个。如果报错集中在某个模块先单独对这个模块执行mvn compile能更快缩小范围。比如对cloud-app单独编译时提示找不到cloud-common的包那么问题大概率出在cloud-common没有正确产出 jar。第二步检查模块的物理目录结构。在命令行里用tree /f或者 Mac/Linux 下的find . -type d看子模块目录确认src/main/java是否存在。这里要注意IDE 里显示的目录和磁盘上真实存在的目录不一定一致有些目录是 IDE 虚拟出来的所以尽量用命令行或文件管理器确认。第三步检查 Maven 工程结构是否被正确识别。如果cloud-common在 IDEA 的 Maven 面板里根本没出现而是作为一个普通目录挂在工程里那说明它的 pom.xml 没有被父子模块关系关联起来。这种情况需要检查父 POM 的modules里有没有声明它以及子 POM 的parent坐标是否正确。第四步检查本地仓库里有没有对应的 jar。路径一般是~/.m2/repository/com/example/cloud-common/1.0.0/cloud-common-1.0.0.jar。如果这个文件不存在说明cloud-common从未成功 install 过。mvn clean会清掉 target 目录但不会清本地仓库所以这里也能反过来判断是不是构建顺序的问题。3.3 修复源码目录并重建依赖关系确认cloud-common缺少源码目录后修复方法其实很简单手动创建标准目录结构。cd cloud-parent/cloud-common mkdir -p src/main/java mkdir -p src/main/resources mkdir -p src/test/java然后回到 IDE在 Maven 面板里点一下刷新让 IDEA 重新解析模块。如果 IDE 没有自动把src/main/java识别成 Sources Root右键目录选择 Mark Directory as → Sources Root 手动标记一下。这一步很容易被忽略目录建好了但 IDE 不认照样会有一堆奇怪的编译问题。接下来是重建依赖关系。这时候只对某个子模块执行mvn compile可能还不够因为它的依赖 jar 还没有被安装到本地仓库。最稳的方式是在根目录cloud-parent下执行完整构建mvn clean install这个命令会从父 POM 开始按模块顺序先编译cloud-common再编译cloud-app、cloud-web并且每个模块都会 install 到本地仓库。只要模块顺序没有问题一轮下来所有依赖就都齐了。还有一个小细节如果某个子模块本来就打算留空只是作为占位那至少给它建好src/main/java并在对应包下放一个package-info.java文件。这样既能保留目录又不会因为空目录被 Git 忽略导致别人克隆后再次踩坑。3.4 重新构建并验证结果补好目录后再执行mvn clean install这次的输出就顺多了。cloud-common模块会出现Compiling 1 source file to .../target/classes的记录后面cloud-app和cloud-web也能正常通过编译。构建结束后进cloud-common/target看一眼classes 目录下会出现com/example/common/util的 class 文件target目录里也会生成cloud-common-1.0.0.jar。到这一步问题就算彻底解决了。整个过程看下来我最大的感受是多模块项目的构建失败绝大多数都不是某个模块的代码炸了而是“模块之间的依赖产物没有按时出现”目录结构只是其中一个最常见的触发器。4. 多模块构建常见问题速查与避坑实录4.1 高频问题定位与解决对照表处理过太多次 Maven 构建问题之后我把高频问题整理成了一个速查表遇到类似情况可以直接对照定位现象可能原因处理方式构建报“源码目录不存在”子模块没有标准源代码目录创建src/main/java等目录并重新刷新 IDE一个模块报“程序包不存在”但代码没问题前序依赖模块没有正确 install 到本地仓库在根目录执行mvn install而非只compile本地仓库有 jar但项目引用不到IDE 配置的 Maven 仓库路径和命令行不一致或坐标版本不匹配检查 IDEA 的 Maven settings清理.lastUpdated后缀文件后重新导入IDEA 识别不了 Maven 项目父 POM/子 POM 关联缺失或工程被当成普通目录打开检查modules和parent配置重新 import 工程依赖全部爆红重新下载后还是报错本地仓库缓存损坏或未下载完整删除对应_remote.repositories和.lastUpdated文件重新mvn -U clean install老项目报找不到com.sun.image.codec.jpeg.JPEGCodec在 JDK 9 中没有该类属于老 JDK 内部 API升级图像处理代码或用兼容 JDK 版本编译不要试图把 JDK 内部类放进 classpathEclipse 更新 Maven 项目时报 internal error本地仓库损坏、IDE 缓存异常或项目存在重复依赖清理 Maven 仓库的损坏文件更新 Maven 项目严重时用干净仓库复现同一个依赖在多个模块里用了不同版本多模块之间没有统一通过父 POM 管理版本在父 POMdependencyManagement统一版本号子模块引用时不写版本这张表基本覆盖了我在这次排查中遇到的所有分支方向。尤其是“本地仓库有 jar 但引不进来”这条经常和“目录未创建”一起出现。比如用mvn clean install构建到一半失败后本地仓库里可能残留了某个模块的上一个版本IDE 误用了旧版本解析结果新代码里引用的新类当然就找不到。4.2 两条能省很多时间的个人习惯第一空模块也要建好源码目录并且放一个文件进去占位。Maven 构建不在乎目录里有没有代码但在乎目录存不存在。Git 默认不跟踪空目录所以就算本地建了src/main/java提交到仓库后别人一克隆目录又消失了。解决办法很简单在每个空目录下放一个package-info.java或者放一个.gitkeep文件把目录占住。这样团队其他人拉代码时目录结构不会被 Git 抹掉。第二不要动不动就对整个工程执行mvn clean。clean会把所有模块的 target 目录清掉严格来说它只影响编译输出不影响本地仓库。但如果在多模块项目中经常只构建部分模块clean会造成一种很微妙的状况旧的 jar 可能还在但 class 文件已经没了IDE 又多了一层旧索引局面会非常乱。我现在的习惯是平时用mvn install只有确定构建产物有问题时才用clean install。这个习惯帮我少踩了很多坑尤其是在本地和 CI 交替构建的项目里。5. 从“目录未创建”延伸出去物理目录、输出目录与仓库目录5.1 三层目录的职责区分如果只记住一个结论我希望是“多模块项目里其实有三层目录”。第一层是物理源码目录也就是src/main/java这些路径第二层是编译输出目录target/classes第三层是本地仓库里的 jar 目录比如~/.m2/repository/com/example/xxx/1.0.0/。物理源码目录管的是“源代码从哪来”target/classes管的是“编译结果放哪”本地仓库的 jar 目录管的是“其他模块从哪找依赖”。三层目录任何一个出问题最终都会表现为编译失败但解决方案完全不同。源码目录缺了就建源码目录target 目录被清了就重新编译本地仓库 jar 缺失了就重新 install。很多人在排查时只看第一层也就是源代码目录忽略了仓库层。尤其是使用 IDE 久了很容易产生一种错觉——项目能跑起来是因为 IDE 记住了所有类的位置。实际上命令行构建时IDE 的记忆完全不生效一切以本地仓库里真实存在的 jar 为准。这就是为什么有些人在 IDE 里跑得出来一上命令行就挂。5.2 按依赖顺序构建与局部构建技巧多模块项目的构建顺序不是随意的Maven 默认按照modules里声明的顺序执行同时也要保证父模块先于子模块被加载。如果模块之间的依赖关系和声明顺序不一致比如cloud-app声明依赖cloud-web但modules里cloud-web排在cloud-app后面构建就可能出现类找不到。如果想只构建某个模块及其上游依赖可以用-pl和-am参数mvn -pl cloud-app -am install-pl表示指定构建的模块-am表示同时构建该模块依赖的其他模块。这个命令在只想验证某个子模块改动的场景下非常实用不用每次都要跑全量构建。需要注意-am只会构建被依赖的上游模块不会构建下游模块所以执行完install后下游模块仍然需要再单独构建或全量构建一次。5.3 几个容易被忽略的构建顺序细节实际项目里最常见的顺序问题不是模块声明错乱而是子模块之间出现循环依赖。比如cloud-common本来应该是最底层的基础模块但有人为了让代码“方便”在cloud-common里引用了cloud-app的某个工具类。这种循环依赖在 IDE 里可能暂时能编译因为 IDE 的增量编译可以容忍但在命令行执行mvn clean install时Maven 会按照模块顺序先构建cloud-common此时它依赖的cloud-app还没有被构建或者还没有 install于是直接报错。在 Maven 多模块设计里依赖方向必须保持单向。基础模块不应该反向依赖业务模块否则构建顺序永远理不顺。检查起来也比较简单在根目录执行mvn dependency:tree可以看到每个模块的实际依赖关系再对照modules声明顺序基本就能发现问题。用到的核心工具类如果实在需要在多个模块间共享应该下沉到cloud-common这类基础模块而不是在业务模块之间互相拉取。这个案例解决完之后我自己在代码审查里也加了一条规则凡是新加子模块先看目录结构是否完整再看依赖方向是否有循环。这个习惯保持了很长时间之后再遇到“目录未创建”相关的构建问题基本都能在几分钟内定位。最后再分享一个小技巧如果你也经常被 Git 空目录坑到就在每个子模块的src/main/java下放一个package-info.java哪怕是空注释也行。这个文件又轻又不影响编译但能保证整个目录结构稳定存在于仓库里。
前两天帮同事排查一个Spring Boot多模块项目mvn clean install跑到一半突然报错内容很直接——某个子模块的源码目录未创建后面跟着一串“程序包不存在”的异常。这种报错在 Maven 多模块项目里其实挺常见但它有个迷惑性第一眼看上去像代码写错了再看又以为是 Maven 没建目录最后折腾下来才发现问题往往出在“构建环境与目录约定”之间的配合上。花了一下午把它解决掉加上之前帮群里朋友看过的几次类似问题今天把完整的排查思路和操作步骤整理出来。如果你也遇到过“目录未创建”“源码目录缺失”“子模块引不到类”这类怪毛病这篇应该能帮你少走不少弯路。1. 多模块项目为什么会报“目录未创建”聚合与继承的底层逻辑1.1 聚合模块、父级 POM 和子模块三者的关系很多刚接触 Maven 多模块的人会把“聚合”和“继承”混在一起。其实 Maven 做多模块有两种机制一种是父 POM 通过modules把子模块聚合起来让所有子模块能一次构建另一种是子模块通过parent继承父 POM 的依赖和插件配置。实际项目里通常会同时用所以你会看到根目录那个 pom.xml 既写了packagingpom/packaging又声明了一堆module。一个典型的结构长这样groupIdcom.example/groupId artifactIdcloud-parent/artifactId version1.0.0/version packagingpom/packaging modules modulecloud-common/module modulecloud-app/module modulecloud-web/module /modules子模块里再通过parent指回父 POM。构建时只要在根目录执行mvn clean installMaven 就会按照模块声明顺序依次构建并且把每个模块打成 jar 安装到本地仓库供后续模块引用。关键点来了既然构建是按顺序来的那么任何一个模块如果没有正常的源码目录结构就会在编译阶段直接断片。断片之后后面所有依赖它的模块都会跟着报错。所以“目录未创建”看起来是个局部小问题实际上影响的是整条构建链路。1.2 “约定优于配置”到底约定了哪些目录Maven 之所以叫构建工具而不是脚本工具核心就是它把大部分规则固定下来了你不需要告诉它源码放哪、资源放哪、测试放哪。它默认有一套标准源码目录${basedir}/src/main/java资源目录${basedir}/src/main/resources测试源码目录${basedir}/src/test/java测试资源目录${basedir}/src/test/resources编译输出目录${basedir}/target/classes打包输出目录${basedir}/target这套约定让所有 Maven 项目看起来都是一个模子换团队、换电脑、换 CI 服务器成本都很低。但也正因为是约定Maven 不会像某些 IDE 那样“贴心”地替你创建这些目录。目录缺失时它只会干巴巴地报一句找不到目录或者找不到符号然后退出构建。很多新手在这里就被绕进去了总觉得 Maven 应该自动把所有标准目录生成好于是盯着mvn archetype:generate找答案。其实用 archetype 确实能生成完整骨架但更多时候你是在已有工程里手动加了一个子模块忘记补目录结构这才是“目录未创建”的高发场景。1.3 目录缺少对构建链路的影响面单模块工程缺个src/main/java后果相对简单要么编译输出为空要么直接构建失败。多模块工程就不一样了它对目录结构的依赖是整个链条式的。举个例子cloud-web依赖cloud-common里的一个工具类。构建时 Maven 会去本地仓库找cloud-common-1.0.0.jar找到之后才能编译 web 模块。如果cloud-common模块自己就缺源码目录它打出来的 jar 就是空的甚至根本打不出来。这时候 web 模块的报错会是“找不到com.example.common.util”之类的程序包不存在而不是直接说目录没建。所以你会看到一种很奇怪的现象整条报错里最显眼的是“程序包不存在”但真正的病根在另一个模块的目录结构上。反过来说如果你在本地 IDE 里能正常跑因为 IDE 有自动编译和索引机制结果命令行构建就挂了那更要先怀疑目录结构而不是代码本身。2. 动手前先搞懂Maven 在编译时到底需要“找到”哪些目录2.1 Java 编译器的视角源码目录与 classpath要彻底搞明白这个问题得站在 javac 的角度看一次编译过程。Maven 调用编译器时会做两件事第一把当前模块src/main/java下的所有.java文件编译成.class文件输出到target/classes第二把当前模块依赖的 jar 包路径拼进 classpath让 javac 能解析到其他模块或第三方库的类。对 javac 来说它拿到的是一个文件路径列表。src/main/java这个路径如果不存在就相当于一个空的输入集合编译出来的结果自然也是空的。而“依赖的 jar 包不存在”换个角度看也等于 classpath 里某个目录或文件缺失。所以你会发现Maven 报错时经常把“目录未创建”“程序包不存在”“找不到符号”混在一起因为它们本质上是同一类问题——编译器要访问的东西不在它预期的位置上。这次我排查的工程报错信息先是“源码目录不存在”后续模块又跟着报“程序包不存在”两种现象同时出现基本可以锁定是前面某个模块没有正常产出 jar而不是业务代码本身有语法问题。2.2 三种“目录未创建”的真实形态同样的报错根因可能完全不同。根据我遇到过的案例大致可以分成三种形态典型现象判断方法解决方向物理目录缺失某个子模块完全没有src/main/javaGit 克隆后目录不存在用文件管理器或 tree 命令查看模块目录结构手动创建标准源码目录或重新用 Maven 骨架生成模块仓库 jar 缺失mvn clean之后没执行install后续模块引用不到前序模块的类查看本地仓库~/.m2/repository下对应模块路径是否真的有 jar在父 POM 根目录执行完整mvn install按依赖顺序安装模块构建上下文错乱IDE 识别不了 Maven 模块或者子模块没有parent关联构建时被当成独立工程打开 IDE 的 Maven 面板看是否列出全部模块检查 pom 引用关系让 IDE 重新导入或关联 Maven 项目修正 parent/modules 配置这三种形态往往会叠加。比如物理目录缺失导致模块 install 出来的 jar 是空的接着引发“程序包不存在”。排查时不要只盯第一行报错要把整个构建日志从头到尾看一遍。2.3 排查前置条件版本、仓库与 settings.xml 配置在开始处理目录问题之前我建议先确认一轮基础环境。这一步看着多余实际上能过滤掉大量干扰项。先跑mvn -v看版本和 Java 版本。Maven 的版本选择不用太纠结3.8.x 和 3.9.x 都是当前主流版本。网上有些标题写着“maven 3.88 下载”的其实官网并没有这个版本号大概率是 3.8.8 的误传下载时认准官方路径就行。如果是在 Windows 7 这类老系统上装尽量选较新的 3.8.x 版本同时确认JAVA_HOME指向的 JDK 版本和项目编译目标一致避免老环境里出现 JDK 类库找不到的问题。然后确认本地仓库位置。默认是~/.m2/repository但很多公司会统一改到自定义目录靠settings.xml里的localRepository指定。如果配了阿里云镜像或者其他私服还要确认 jar 包的下载路径是否和当前使用的settings.xml对应。经常有人本地明明有某个 jar项目里却一直报找不到就是因为 IDE 里配置的 Maven 仓库路径和命令行用的不是同一个。顺手贴一个常用的国内镜像配置能解决大部分依赖下载慢和下载失败的问题mirrors mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors不要贪多一次配一个主镜像就够了。配置多个镜像有时反而会在依赖解析时引入不确定因素尤其是在多模块项目里某个模块先去错误的仓库找依赖构建速度会拖慢很久报错也五花八门。3. 完整排查流程从报错日志到目录修复再到构建通过3.1 复现场景cloud-parent 多模块工程案例为了把过程讲清楚我构造一个和当时几乎一样的工程示例。父模块叫cloud-parent下面挂了三个子模块cloud-parent ├── pom.xml ├── cloud-common │ └── pom.xml ├── cloud-app │ ├── pom.xml │ └── src/main/java/com/example/app/AppApplication.java └── cloud-web ├── pom.xml └── src/main/java/com/example/web/WebApplication.java出问题的模块是cloud-common。它的 pom.xml 基本是复制父 POM 里的配置但目录结构里只有pom.xml没有src/main/java。也就是说这个模块现在是一个“空心”模块。我在根目录执行mvn clean install后cloud-common模块本身可能不会立刻报错因为空模块在 Maven 眼里也算一个合法模块它会生成一个不含 class 的 jar。真正崩掉的是下一个环节——cloud-app编译时找不到cloud-common里的类。日志里的关键错误长这样[ERROR] /path/to/cloud-app/src/main/java/com/example/app/AppApplication.java:[4,17] 程序包com.example.common.util不存在 [ERROR] /path/to/cloud-app/src/main/java/com/example/app/AppApplication.java:[8,34] 找不到符号这种报错非常容易让人误判成代码里依赖写错或者 jar 没下下来。但把cloud-common的src目录加回来之后整个构建立刻恢复。说白了这个模块从一开始就没有源码自然也就无法提供任何类给下游模块。3.2 分步定位先判断是哪一种“目录缺失”遇到报错先别慌按下面几步快速定位。第一步看构建日志里报错所属的模块是哪一个。如果报错集中在某个模块先单独对这个模块执行mvn compile能更快缩小范围。比如对cloud-app单独编译时提示找不到cloud-common的包那么问题大概率出在cloud-common没有正确产出 jar。第二步检查模块的物理目录结构。在命令行里用tree /f或者 Mac/Linux 下的find . -type d看子模块目录确认src/main/java是否存在。这里要注意IDE 里显示的目录和磁盘上真实存在的目录不一定一致有些目录是 IDE 虚拟出来的所以尽量用命令行或文件管理器确认。第三步检查 Maven 工程结构是否被正确识别。如果cloud-common在 IDEA 的 Maven 面板里根本没出现而是作为一个普通目录挂在工程里那说明它的 pom.xml 没有被父子模块关系关联起来。这种情况需要检查父 POM 的modules里有没有声明它以及子 POM 的parent坐标是否正确。第四步检查本地仓库里有没有对应的 jar。路径一般是~/.m2/repository/com/example/cloud-common/1.0.0/cloud-common-1.0.0.jar。如果这个文件不存在说明cloud-common从未成功 install 过。mvn clean会清掉 target 目录但不会清本地仓库所以这里也能反过来判断是不是构建顺序的问题。3.3 修复源码目录并重建依赖关系确认cloud-common缺少源码目录后修复方法其实很简单手动创建标准目录结构。cd cloud-parent/cloud-common mkdir -p src/main/java mkdir -p src/main/resources mkdir -p src/test/java然后回到 IDE在 Maven 面板里点一下刷新让 IDEA 重新解析模块。如果 IDE 没有自动把src/main/java识别成 Sources Root右键目录选择 Mark Directory as → Sources Root 手动标记一下。这一步很容易被忽略目录建好了但 IDE 不认照样会有一堆奇怪的编译问题。接下来是重建依赖关系。这时候只对某个子模块执行mvn compile可能还不够因为它的依赖 jar 还没有被安装到本地仓库。最稳的方式是在根目录cloud-parent下执行完整构建mvn clean install这个命令会从父 POM 开始按模块顺序先编译cloud-common再编译cloud-app、cloud-web并且每个模块都会 install 到本地仓库。只要模块顺序没有问题一轮下来所有依赖就都齐了。还有一个小细节如果某个子模块本来就打算留空只是作为占位那至少给它建好src/main/java并在对应包下放一个package-info.java文件。这样既能保留目录又不会因为空目录被 Git 忽略导致别人克隆后再次踩坑。3.4 重新构建并验证结果补好目录后再执行mvn clean install这次的输出就顺多了。cloud-common模块会出现Compiling 1 source file to .../target/classes的记录后面cloud-app和cloud-web也能正常通过编译。构建结束后进cloud-common/target看一眼classes 目录下会出现com/example/common/util的 class 文件target目录里也会生成cloud-common-1.0.0.jar。到这一步问题就算彻底解决了。整个过程看下来我最大的感受是多模块项目的构建失败绝大多数都不是某个模块的代码炸了而是“模块之间的依赖产物没有按时出现”目录结构只是其中一个最常见的触发器。4. 多模块构建常见问题速查与避坑实录4.1 高频问题定位与解决对照表处理过太多次 Maven 构建问题之后我把高频问题整理成了一个速查表遇到类似情况可以直接对照定位现象可能原因处理方式构建报“源码目录不存在”子模块没有标准源代码目录创建src/main/java等目录并重新刷新 IDE一个模块报“程序包不存在”但代码没问题前序依赖模块没有正确 install 到本地仓库在根目录执行mvn install而非只compile本地仓库有 jar但项目引用不到IDE 配置的 Maven 仓库路径和命令行不一致或坐标版本不匹配检查 IDEA 的 Maven settings清理.lastUpdated后缀文件后重新导入IDEA 识别不了 Maven 项目父 POM/子 POM 关联缺失或工程被当成普通目录打开检查modules和parent配置重新 import 工程依赖全部爆红重新下载后还是报错本地仓库缓存损坏或未下载完整删除对应_remote.repositories和.lastUpdated文件重新mvn -U clean install老项目报找不到com.sun.image.codec.jpeg.JPEGCodec在 JDK 9 中没有该类属于老 JDK 内部 API升级图像处理代码或用兼容 JDK 版本编译不要试图把 JDK 内部类放进 classpathEclipse 更新 Maven 项目时报 internal error本地仓库损坏、IDE 缓存异常或项目存在重复依赖清理 Maven 仓库的损坏文件更新 Maven 项目严重时用干净仓库复现同一个依赖在多个模块里用了不同版本多模块之间没有统一通过父 POM 管理版本在父 POMdependencyManagement统一版本号子模块引用时不写版本这张表基本覆盖了我在这次排查中遇到的所有分支方向。尤其是“本地仓库有 jar 但引不进来”这条经常和“目录未创建”一起出现。比如用mvn clean install构建到一半失败后本地仓库里可能残留了某个模块的上一个版本IDE 误用了旧版本解析结果新代码里引用的新类当然就找不到。4.2 两条能省很多时间的个人习惯第一空模块也要建好源码目录并且放一个文件进去占位。Maven 构建不在乎目录里有没有代码但在乎目录存不存在。Git 默认不跟踪空目录所以就算本地建了src/main/java提交到仓库后别人一克隆目录又消失了。解决办法很简单在每个空目录下放一个package-info.java或者放一个.gitkeep文件把目录占住。这样团队其他人拉代码时目录结构不会被 Git 抹掉。第二不要动不动就对整个工程执行mvn clean。clean会把所有模块的 target 目录清掉严格来说它只影响编译输出不影响本地仓库。但如果在多模块项目中经常只构建部分模块clean会造成一种很微妙的状况旧的 jar 可能还在但 class 文件已经没了IDE 又多了一层旧索引局面会非常乱。我现在的习惯是平时用mvn install只有确定构建产物有问题时才用clean install。这个习惯帮我少踩了很多坑尤其是在本地和 CI 交替构建的项目里。5. 从“目录未创建”延伸出去物理目录、输出目录与仓库目录5.1 三层目录的职责区分如果只记住一个结论我希望是“多模块项目里其实有三层目录”。第一层是物理源码目录也就是src/main/java这些路径第二层是编译输出目录target/classes第三层是本地仓库里的 jar 目录比如~/.m2/repository/com/example/xxx/1.0.0/。物理源码目录管的是“源代码从哪来”target/classes管的是“编译结果放哪”本地仓库的 jar 目录管的是“其他模块从哪找依赖”。三层目录任何一个出问题最终都会表现为编译失败但解决方案完全不同。源码目录缺了就建源码目录target 目录被清了就重新编译本地仓库 jar 缺失了就重新 install。很多人在排查时只看第一层也就是源代码目录忽略了仓库层。尤其是使用 IDE 久了很容易产生一种错觉——项目能跑起来是因为 IDE 记住了所有类的位置。实际上命令行构建时IDE 的记忆完全不生效一切以本地仓库里真实存在的 jar 为准。这就是为什么有些人在 IDE 里跑得出来一上命令行就挂。5.2 按依赖顺序构建与局部构建技巧多模块项目的构建顺序不是随意的Maven 默认按照modules里声明的顺序执行同时也要保证父模块先于子模块被加载。如果模块之间的依赖关系和声明顺序不一致比如cloud-app声明依赖cloud-web但modules里cloud-web排在cloud-app后面构建就可能出现类找不到。如果想只构建某个模块及其上游依赖可以用-pl和-am参数mvn -pl cloud-app -am install-pl表示指定构建的模块-am表示同时构建该模块依赖的其他模块。这个命令在只想验证某个子模块改动的场景下非常实用不用每次都要跑全量构建。需要注意-am只会构建被依赖的上游模块不会构建下游模块所以执行完install后下游模块仍然需要再单独构建或全量构建一次。5.3 几个容易被忽略的构建顺序细节实际项目里最常见的顺序问题不是模块声明错乱而是子模块之间出现循环依赖。比如cloud-common本来应该是最底层的基础模块但有人为了让代码“方便”在cloud-common里引用了cloud-app的某个工具类。这种循环依赖在 IDE 里可能暂时能编译因为 IDE 的增量编译可以容忍但在命令行执行mvn clean install时Maven 会按照模块顺序先构建cloud-common此时它依赖的cloud-app还没有被构建或者还没有 install于是直接报错。在 Maven 多模块设计里依赖方向必须保持单向。基础模块不应该反向依赖业务模块否则构建顺序永远理不顺。检查起来也比较简单在根目录执行mvn dependency:tree可以看到每个模块的实际依赖关系再对照modules声明顺序基本就能发现问题。用到的核心工具类如果实在需要在多个模块间共享应该下沉到cloud-common这类基础模块而不是在业务模块之间互相拉取。这个案例解决完之后我自己在代码审查里也加了一条规则凡是新加子模块先看目录结构是否完整再看依赖方向是否有循环。这个习惯保持了很长时间之后再遇到“目录未创建”相关的构建问题基本都能在几分钟内定位。最后再分享一个小技巧如果你也经常被 Git 空目录坑到就在每个子模块的src/main/java下放一个package-info.java哪怕是空注释也行。这个文件又轻又不影响编译但能保证整个目录结构稳定存在于仓库里。
