Gradle多模块循环依赖必须手动打破闭环，常见于双向project引用、settings.gradle模块重名、传递依赖或buildSrc动态注入；应抽离共享内容至独立模块、重命名冲突子项目、检查依赖树并修正分层设计。
Gradle多模块项目出现循环依赖，基本可以确定是模块间存在双向引用或构建配置错误，不是Gradle“自动修复不了”，而是它明确拒绝这种非法结构——必须手动打破闭环。
检查 build.gradle 中的 implementation project(...) 是否双向声明
最常见的循环依赖来源是两个模块互相用 implementation project(':xxx') 引用对方。比如 :service 依赖 :model，而 :model 又反向依赖 :service（例如为了调用某个工具类或常量）。Gradle 在解析依赖图时会立即报错，典型错误信息类似：
Circular dependency between the following tasks: :service:classes :service:jar :model:classes :model:jar
这类错误往往不是代码逻辑问题，而是构建层误配。解决方法很直接：
- 逐个打开子模块的
build.gradle，搜索project(，确认所有implementation project(...)、api project(...)都是单向的 - 如果确实需要共享内容（如 DTO、常量），应抽离到一个三方模块（如
:common），让双方都依赖它，而不是彼此依赖 - 避免在
:model这类数据层模块里引入任何业务逻辑或服务类的引用
警惕 settings.gradle 中同名子项目引发的隐式循环
当多个子项目路径不同但末尾名称相同（例如 :lib:auth:model 和 :lib:order:model），Gradle 在某些版本中会因内部短名解析歧义，把它们当成同一个模块处理，进而误判为循环依赖。这种错误不报具体路径，只提示“circular dependency detected”，极难定位。
验证方式：在根目录执行 ./gradlew projects，查看输出中是否出现重复的 model 条目（如两个都显示为 model - model module）。
- 必须重命名冲突模块，确保每个
include后的路径末尾名称全局唯一，例如改为:lib:auth:auth-model和:lib:order:order-model - 重命名后，所有
project(...)引用语句也需同步更新，否则会报Project with path ':xxx' could not be found - IDE（如 IntelliJ）可能缓存旧项目结构，修改后需执行
File → Reload project或删除.idea目录重新导入
用 ./gradlew dependencies --configuration compileClasspath 查真实依赖链
光看 build.gradle 容易漏掉传递依赖导致的间接循环。比如 :web 依赖 :service，而 :service 的某个第三方库又意外拉入了 :web 的某个 jar（常见于自定义 starter 或未收敛的 BOM）。
运行该命令可展开每个模块的完整编译期依赖树，重点观察是否有跨模块的“回指”路径：
- 查找类似
+--- project :web出现在:service的依赖树底部的情况 - 注意带
(*)标记的已省略分支，必要时加--scan生成 Gradle Build Scan 查看全图 - 若发现第三方库引入了不该有的模块，用
exclude排除，或升级/降级该库版本
别忽略 buildSrc 或 init.gradle 里的动态依赖逻辑
有些团队会在 buildSrc 里写 Kotlin/Groovy 脚本，通过遍历子项目自动添加依赖；或者用 init.gradle 全局 hook afterEvaluate 注入逻辑。这类代码不会出现在 build.gradle 里，但同样能制造循环。
- 检查
buildSrc/src/main/groovy/下是否有类似subprojects { it.dependencies { implementation project(...) } }的全局注入 - 检查
init.gradle或gradle.properties是否启用了影响依赖解析的实验性特性（如enableFeaturePreview('VERSION_CATALOGS')在旧版 Gradle 中可能引发解析异常） - 临时注释掉
buildSrc或init.gradle，再运行构建，看循环是否消失——这是最有效的隔离手段
循环依赖不是 Gradle 的 bug，而是项目结构失衡的明确信号。真正难的不是修复那几行 project(...)，而是识别出哪部分逻辑本就不该放在那个模块里——比如把校验逻辑塞进 :model，本质是分层混乱，改配置只是治标。
