1. 问题现象与背景解析
最近在使用IntelliJ IDEA进行Java项目开发时，遇到了一个令人头疼的弹窗提示："Cannot Save Settings - Source root '...' is duplicated in module '...'"。这个错误通常发生在修改项目配置或导入新模块时，系统检测到源代码根目录(Source root)在模块(module)中出现了重复定义。
作为一款主流的Java集成开发环境，IDEA通过模块化方式管理项目结构。每个模块可以包含多个源代码根目录（标记为蓝色的文件夹），这些目录会被编译器识别并用于代码索引、构建和调试。当同一个物理路径被多次标记为源代码根目录时，就会触发这个保护机制。
注意：该错误与IDEA版本无关，社区版和旗舰版都可能出现，主要原因是项目配置冲突而非软件缺陷。
2. 错误产生的典型场景
2.1 多模块项目配置冲突
在Maven或Gradle的多模块项目中，如果父模块和子模块都包含了相同的src/main/java目录，就可能出现这种重复。例如：
project/ ├── pom.xml (父模块) └── submodule/ └── src/main/java (子模块)当这两个模块都试图将java目录声明为Source root时就会冲突。
2.2 错误的手动配置
通过右键菜单"Mark Directory as"手动标记源代码目录时，如果误操作将同一目录多次标记为Sources Root，也会产生此问题。
2.3 项目导入时的配置残留
从其他开发环境迁移项目或从版本控制系统检出时，旧的.iml模块配置文件可能包含过时的路径配置，与新生成的配置产生冲突。
3. 解决方案实操指南
3.1 方法一：通过项目结构界面修复
- 打开项目设置：File > Project Structure (快捷键Ctrl+Alt+Shift+S)
- 在左侧选择出现问题的模块
- 切换到"Sources"标签页
- 检查所有标记为蓝色的目录（Sources Root）
- 右键点击重复的目录，选择"Unmark as Sources Root"
- 保留唯一正确的源代码根目录
- 点击OK保存配置
3.2 方法二：直接编辑模块配置文件
对于熟悉IDEA配置的高级用户：
- 关闭IDEA
- 在项目根目录下找到.idea文件夹
- 定位到对应模块的.iml文件
- 用文本编辑器打开，查找重复的 标签
- 删除重复条目，保留一个有效配置
- 重新启动IDEA
3.3 方法三：重建模块配置
当不确定具体冲突位置时：
- 备份项目
- 删除.idea文件夹和所有.iml文件
- 重新导入项目
- 让IDEA重新生成所有配置
4. 深度排查与预防措施
4.1 配置冲突的根本原因
IDEA的模块配置存储在两部分：
- 项目级配置：.idea/modules.xml
- 模块级配置：*.iml文件
当这两个配置文件中关于源代码路径的定义不一致时，就会产生冲突。特别是在多人协作项目中，不同开发者可能使用不同方式配置项目结构。
4.2 预防重复配置的最佳实践
- 统一团队配置规范：约定使用Maven/Gradle标准目录结构
- 避免手动标记源代码目录：优先使用构建工具的标准配置
- 版本控制配置：将.idea文件夹中的modules.xml和*.iml文件加入.gitignore
- 定期清理无效配置：使用File > Invalidate Caches功能
4.3 高级排查技巧
当常规方法无效时，可以：
- 启用IDEA内部日志：Help > Diagnostic Tools > Show Log in Explorer
- 搜索"duplicated source root"相关日志
- 检查是否有隐藏的模块依赖或库配置冲突
5. 常见问题解决方案速查表
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 保存设置时报错 | 源代码目录重复标记 | 检查并删除重复的Sources Root标记 |
| 导入项目后立即报错 | 旧配置残留 | 删除.idea文件夹和所有.iml文件后重新导入 |
| 仅特定模块报错 | 该模块配置错误 | 单独修复该模块的.iml文件 |
| 所有操作无效 | 缓存损坏 | File > Invalidate Caches / Restart |
6. 实际案例解析
最近处理的一个典型案例：一个Spring Boot多模块项目在从GitLab检出后持续报错。排查过程如下：
- 发现父模块和web子模块都包含了src/main/java
- 检查父模块的pom.xml，确认已正确配置
- 发现子模块的.iml文件中存在两个相同的 标签
- 删除重复标签后问题解决
- 根本原因是某位开发者手动标记了源代码目录
这个案例的教训是：在标准Maven项目中，应该完全依赖pom.xml管理源代码目录，避免手动干预。
7. 配置管理的经验分享
经过多年使用IDEA的经验，我总结出以下配置管理原则：
- 构建工具优先：让Maven/Gradle管理源代码目录，减少手动配置
- 版本控制策略：只提交必要的配置，忽略自动生成的文件
- 定期维护：每个季度检查一次项目配置，清理无效条目
- 团队统一：建立项目配置规范文档，新成员入职时培训
对于大型项目，建议创建一个init.gradle或init.sh脚本，统一初始化开发环境配置，避免个人配置差异导致的问题。