为settings.gradle.kts配置自定义Gradle插件遇取值异常问题

这不是Gradle 7.5.1的Bug，是未遵循Gradle扩展属性标准使用规范导致的问题。

核心原因 #

Gradle的扩展属性（无论用于Project还是Settings场景）在读取时必须处于已初始化状态——要么用户在配置脚本中显式赋值，要么通过convention给属性设置默认值。如果两者都未执行，当插件尝试读取属性值时，Gradle就会抛出"无法查询属性值，因无可用值"的错误。

为什么加convention就正常？ #

convention的作用是为属性提供默认 fallback 值：即使用户没有在settings.gradle.kts中配置该属性，插件读取时也能拿到这个默认值，避免属性处于未初始化的空状态。

正确的使用方式 #

根据需求选择两种方案之一：

• 方案1：可选属性（带默认值）
  适合用户可配置也可不配置的属性，定义时通过convention设置默认值：

  // 插件扩展类中的属性定义示例
  class FooSettingsExtension(settings: Settings) {
      val myPropertyToConfigure = settings.objects.property<String>().convention("default-value")
  }
  

• 方案2：必填属性
  如果该属性是用户必须配置的，不需要设置默认值，但要确保插件读取属性前，用户已经在settings.gradle.kts中完成赋值：

  // 扩展类定义
  class FooSettingsExtension(settings: Settings) {
      val myPropertyToConfigure = settings.objects.property<String>()
  }
  // 用户配置脚本中必须添加
  fooSettingsPlugin {
      myPropertyToConfigure.set("user-configured-value")
  }
  

补充说明 #

Gradle 7.5.1对属性初始化的校验符合官方规范，这种设计是为了避免插件读取未定义属性导致的不可预期行为，强制开发者明确属性的初始化逻辑。

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