Gradle Settings插件modules扩展在settings.gradle.kts中无法识别

开发Settings级Gradle插件时，插件已经成功应用（控制台打印了应用日志），但在settings.gradle.kts中调用自定义的modules配置块时提示未解析引用，无法正常使用。

插件实现代码 #

public class SettingsPlugin implements Plugin<Settings> {
    @Override
    public void apply(Settings target) {
        target.getExtensions()
              .create("modules", IncludeModulesExtension.class, target);

        System.err.println("Applied settings plugin");
    }
}

public class IncludeModulesExtension {
    private final Settings _settings;

    public IncludeModulesExtension(Settings settings) {
        _settings = settings;
    }

    public void include(String path) {
        // 初始为空实现
    }
}

问题配置 #

pluginManagement {
    // 省略配置内容
}

plugins {
    id("com.ieffects.gradle-tools.settings-server") version ("7.0.23-SNAPSHOT")
}

modules {
    // 配置内容
}

报错信息 #

Starting Gradle Daemon...
Gradle Daemon started in 2 s 396 ms
Applied settings plugin
e: /Volumes/Development/Git/server-framework-galcon/settings.gradle.kts:22:1: Unresolved reference: modules

FAILURE: Build failed with an exception.

* Where:
Settings file '/Volumes/Development/Git/server-framework-galcon/settings.gradle.kts' line: 22

* What went wrong:
Script compilation error:

  Line 22: modules {
           ^ Unresolved reference: modules

1 error

这个问题是Kotlin DSL的静态编译特性导致的：

• Groovy DSL是动态分发，注册扩展后可以直接通过扩展名字调用配置块，不需要提前生成符号
• Kotlin DSL是静态编译，和Project级插件不同，Settings级插件通过plugins块应用时，Gradle默认不会为注册的扩展自动生成顶层的访问函数，编译器在编译settings脚本时找不到modules这个符号，就会抛出未解析引用的错误。
  控制台打印了插件应用日志，说明插件本身加载、扩展注册流程都是正常的，只是脚本侧的访问方式不对。

方案1：显式调用扩展配置（零插件代码修改，最快修复） #

不需要修改插件代码，直接在settings脚本中通过configure泛型方法显式获取扩展实例进行配置即可，写法如下：

pluginManagement {
    // 保留原有配置
}

plugins {
    id("com.ieffects.gradle-tools.settings-server") version ("7.0.23-SNAPSHOT")
}

// 显式指定扩展类型进行配置，替换为你自己的扩展类全限定名
configure<IncludeModulesExtension> {
    // 这里写配置逻辑，比如 include(":common:core")
}

注意要确保IncludeModulesExtension类是插件对外暴露的公开API类，能被构建脚本访问到。另外当前IncludeModulesExtension的include方法是空实现，记得补充实际逻辑：

public void include(String path) {
    _settings.include(path);
}

方案2：配置Kotlin DSL访问器生成（保留modules {}简写语法） #

如果想和Groovy DSL一样直接用modules {}的简写写法，需要给插件添加Kotlin DSL支持：

• 在插件项目的构建脚本中添加Kotlin DSL依赖：

  dependencies {
      implementation(gradleKotlinDsl())
  }
  

• 确保插件使用java-gradle-plugin进行开发，正确声明插件id，Gradle会在插件发布时自动生成对应的Kotlin DSL访问器，后续在settings脚本中应用插件后就可以直接识别modules顶层配置块。

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