IntelliJ对依赖替换（版本目录转本地项目）支持不全的解决方案求助

背景 #

我在根项目的build.gradle.kts中编写了如下代码，实现将版本目录中的依赖替换为本地项目：

fun DependencySubstitutions.substitute(
    lib: Provider<MinimalExternalModuleDependency>,
    module: String,
) {
    val dep = lib.get()
    val notation = "${dep.module.group}:${dep.module.name}"
    substitute(module(notation)).using(project(module))
}

subprojects {
    configurations.configureEach {
        resolutionStrategy {
            dependencySubstitution {
                if (project.providers.gradleProperty("useLocalToolbox").get().toBoolean() == true()) {
                    substitute(deps.toolbox.core, ":toolbox:core")
                    substitute(deps.toolbox.app, ":toolbox:app")
                    substitute(deps.toolbox.ui, ":toolbox:modules:ui")
                    substitute(deps.toolbox.zip, ":toolbox:modules:zip")
                    substitute(deps.toolbox.csv, ":toolbox:modules:csv")
                    substitute(deps.toolbox.backup, ":toolbox:modules:backup")
                    substitute(deps.toolbox.service, ":toolbox:modules:service")
                    substitute(deps.toolbox.form, ":toolbox:modules:form")
                    substitute(deps.toolbox.table, ":toolbox:modules:table")
                    substitute(deps.toolbox.proversion, ":toolbox:modules:proversion")
                    substitute(deps.toolbox.ads, ":toolbox:modules:ads")
                    substitute(deps.toolbox.room, ":toolbox:modules:room")
                }
            }
        }
    }
}

该配置可正常完成编译与构建，但IntelliJ无法识别依赖替换操作，导致诸多问题：

• IDE将正常代码（导入语句及「缺失」函数的用法）标记为无效；
• 若目标函数未包含在发布版本中，Shift+Enter导入功能无法使用；
• 对于同时存在于两个版本的函数，跳转定义时总是跳转到被替换的代码而非替换后的本地代码。

已尝试Invalidate Caches并重启IDE，但问题仍存在多年。项目使用Kotlin Multiplatform，运行在Windows环境下的IntelliJ。

解决方案 #

方案1：显式声明依赖切换 #

IntelliJ对动态依赖替换（基于Gradle属性判断）的支持有限，建议将替换逻辑改为在dependencies块中显式声明，通过Gradle属性控制本地/远程依赖的切换：

subprojects {
    val useLocalToolbox = project.providers.gradleProperty("useLocalToolbox")
        .map { it.toBoolean() }
        .getOrElse(false)

    dependencies {
        if (useLocalToolbox) {
            implementation(project(":toolbox:core"))
            implementation(project(":toolbox:app"))
            implementation(project(":toolbox:modules:ui"))
            // 其他本地依赖声明
        } else {
            implementation(deps.toolbox.core)
            implementation(deps.toolbox.app)
            implementation(deps.toolbox.ui)
            // 其他远程依赖声明
        }
    }
}

这种显式声明的方式能让IntelliJ清晰识别依赖来源，避免动态替换带来的IDE识别问题。

方案2：使用Gradle Composite Builds替代依赖替换 #

Composite Builds是Gradle官方推荐的本地依赖替换方案，对IntelliJ的支持更完善：

1. 在根项目的settings.gradle.kts中添加：

if (providers.gradleProperty("useLocalToolbox").getOrElse("false").toBoolean()) {
    includeBuild("../toolbox") // 替换为toolbox项目的实际本地路径
}

2. 移除原build.gradle.kts中的依赖替换逻辑，保持原有的远程依赖声明即可。

Composite Builds会自动将远程依赖替换为本地项目，且IntelliJ能完全识别这种替换，代码跳转、补全功能都能正常工作。

方案3：强制IntelliJ同步时加载指定属性 #

在IntelliJ的Gradle配置中手动添加useLocalToolbox=true属性，确保同步时能识别替换逻辑：

• 打开File > Settings > Build, Execution, Deployment > Build Tools > Gradle
• 在Program arguments中添加-PuseLocalToolbox=true
• 重新同步Gradle项目

内容的提问来源于stack exchange，提问作者prom85