IDEA 多项目模式不识别 Maven 项目的解决

场景

在 IntelliJ IDEA 中以多项目目录方式打开一个父文件夹（例如 /bolierplate/java/），该父目录下有多个独立的子项目：

bolierplate/java/
├── eladmin/
├── mall/
├── ruoyi-vue-pro/
├── spring-boot-init-template/
├── spring-boot-microservice-best-practices/
└── spring-template/          # 我的 Spring Boot 多模块项目
    ├── pom.xml
    ├── spring-template-common/
    ├── spring-template-framework/
    ├── spring-template-system/
    └── spring-template-server/

此时 spring-template 不会被识别为 Java/Maven 项目，表现为：

代码没有语法高亮
import 全部飘红
Maven 工具窗口里看不到该项目
右键 pom.xml 没有 Add as Maven Project 之外的任何选项
单独打开 spring-template/ 目录却一切正常

原因分析

IDEA 打开项目的规则：

单独打开 spring-template/ ：IDEA 检测到根目录有 pom.xml，自动触发 Maven 导入，生成带 Maven facet 的 .iml 文件
多项目模式打开父目录 bolierplate/java/：IDEA 以父目录的 .idea/ 为准，不会递归扫描子目录的 pom.xml

查看 spring-template/.idea/modules.xml 只注册了一个空壳模块：

<modules>
  <module fileurl="file://$PROJECT_DIR$/spring-template.iml"
          filepath="$PROJECT_DIR$/spring-template.iml" />
</modules>

而 spring-template.iml 只是把根目录标为 source folder，并没有 Maven facet：

<module version="4">
  <component name="AdditionalModuleElements">
    <content url="file://$MODULE_DIR$" dumb="true">
      <sourceFolder url="file://$MODULE_DIR$" isTestSource="false" />
    </content>
  </component>
</module>

所以 IDE 只把它当成一个普通 Java 源码目录，不知道依赖、不知道子模块聚合关系。

解决方案

方案一：手动导入 Maven 模块（推荐，已验证可行）

在多项目模式的 IDEA 窗口里：

File → Project Structure → Modules
点左上角 + → Import Module
选择 spring-template/pom.xml
选择 Import module from external model → Maven
一路 Next → Finish

导入后 IDEA 会自动解析依赖，所有子模块（common / framework / system / server）一并被识别。

方案二：通过 Maven 工具窗口添加

打开右侧 Maven 面板
点击 +（Add Maven Projects）
选择 spring-template/pom.xml
等待依赖下载完成

方案三：单独打开（最干净）

直接 File → Open → 选 spring-template/ 目录，作为独立窗口打开。

适用于只需要专注在一个项目上的场景，不受其他项目的 .idea/ 配置干扰。

后续注意

方案一导入后，spring-template/.idea/modules.xml 会新增 4 个子模块的 iml 引用
如果切换分支/拉取代码导致 .iml 文件丢失，重新执行方案一即可
避免把 spring-template/.idea/ 整体提交到 git（已在 .gitignore 中忽略），否则会影响其他人的 IDE 配置

为什么 WebStorm / VSCode 没这个问题

VSCode：每个子目录都可以作为 workspace folder 独立加载扩展，Extension Pack for Java 会递归扫描 pom.xml
WebStorm：前端项目没有 Maven 这类强依赖于聚合配置的构建工具，package.json 是独立的，不存在多模块聚合问题

IDEA 的 Maven 支持依赖项目根的 .idea/ 配置，这是一个历史设计问题。