Gradle Kotlin DSL中setProperty方法与普通变量的差异对比

底层本质差异 #

两者虽然看起来都是给myMainClass赋了同一个值，但归属的存储体系完全无关：

• 直接写val myMainClass = "MainClass"：本质是Kotlin脚本编译阶段生成的编译期局部变量，属于当前脚本类的临时字段，完全没有进入Gradle内置的Project属性映射体系，不受Gradle构建生命周期的统一管理。
• 调用setProperty("myMainClass", "MainClass")：本质是直接写入Gradle全局的Project属性存储表，写入的值会被纳入Gradle统一的属性作用域管理，和命令行传入的-P参数、gradle.properties文件配置走同一套存储链路。

setProperty() 相比普通变量的实际使用优势 #

这些优势不是语法层面的细碎差异，是直接适配Gradle构建机制带来的实际开发体验区别，也是很多老开发者习惯用Project属性存值而不是直接写脚本变量的核心原因：

• 全构建周期、跨脚本可见
  普通声明的val变量仅在当前脚本的顶层执行帧内有效，哪怕是同一个脚本里的afterEvaluate回调、task的实际执行动作块，都可能因为作用域不匹配访问不到这个变量，甚至出现编译报错。很多新手刚用Kotlin DSL时碰到“明明在顶层声明了变量，为啥在task块里就报未解析引用”的问题，本质就是普通val的作用域根本延伸不到这些异步回调块里。而通过setProperty()写入的属性，只要Project实例存活，不管在哪个构建回调、哪个子脚本、哪个task配置块中，都可以通过标准的属性查询方法正常取值。
• 原生兼容Gradle配置缓存机制
  脚本中直接声明的普通val变量，是绑定在脚本编译生成的临时类实例上的，开启配置缓存后，这类临时类不会被长期持有，很容易触发序列化报错，或者出现取值为空的不可预期问题。而通过setProperty()写入的Project属性，本身就是配置缓存机制官方支持的存储格式，会被正确序列化到缓存快照中，完全没有兼容风险。
• 打通多来源属性的统一读写逻辑
  Gradle的Project属性存储是有固定优先级的：外部传入的命令行参数、gradle.properties配置会和脚本内通过setProperty()写入的默认值走同一套查询通道。比如你在脚本里用setProperty("myMainClass", "默认主类")设置了默认值，后续如果用户在命令行传入-PmyMainClass=自定义主类，Gradle会自动按优先级取到自定义的值，不需要额外写判断逻辑覆盖默认值。
• 可被增量构建机制识别
  当你把通过setProperty()存储的属性绑定为task的输入参数时，Gradle的增量编译检测机制可以自动感知到属性值的变化，在值变动时自动触发对应task重跑。而普通val变量因为不在Project属性体系内，Gradle的增量检测机制完全感知不到这个值的变化，很容易出现修改了变量值、但task因为缓存命中没有重新执行的问题。
• 天然支持跨项目属性传递
  在根项目脚本中通过setProperty()写入的属性，可以直接被子项目通过rootProject.property("属性名")读取，不需要手动编写扩展配置做跨项目透传。而普通脚本声明的val变量，哪怕在根项目顶层定义，子项目脚本也完全没有办法访问，要实现跨项目传值还得额外编写大量样板代码挂载到Project扩展上。

很多开发者刚接触Kotlin DSL时容易踩坑：会把脚本顶层声明的val变量误判为Gradle可全局访问的Project属性，实际上这类Kotlin语法层面的临时变量，和Gradle本身的构建调度机制完全没有绑定，只是脚本编译后的普通类字段而已。

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