属性与变量

局部变量

局部变量仅在声明的脚本范围内有效：

// build.gradle.kts
val springBootVersion = "3.2.0"
val javaVersion = 17

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web:$springBootVersion")
}

java {
    sourceCompatibility = JavaVersion.toVersion(javaVersion)
}

extra 扩展属性

extra（也称 ext）属性可以跨脚本共享，用于多项目构建中的版本统一管理。

// 根项目 build.gradle.kts
extra["springBootVersion"] = "3.2.0"
extra["junitVersion"] = "5.10.1"

// 委托语法（推荐，有类型推断）
val springBootVersion by extra("3.2.0")
val junitVersion by extra("5.10.1")

子项目中读取：

// 子项目 build.gradle.kts
val springBootVersion: String by rootProject.extra

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web:$springBootVersion")
}

Gradle 项目属性

通过命令行传递

# -P 传递项目属性
./gradlew build -PbuildEnv=production -PappVersion=2.0.0

// build.gradle.kts 中访问
val buildEnv = project.findProperty("buildEnv") as String? ?: "development"
val appVersion = project.property("appVersion")  // 属性不存在时抛出异常

// 简洁写法
if (project.hasProperty("releaseMode")) {
    // 发布模式配置
}

通过 gradle.properties 定义

# gradle.properties
appVersion=1.0.0
buildEnv=development

// build.gradle.kts 中直接使用（Kotlin DSL 委托）
val appVersion: String by project
val buildEnv: String by project

系统属性与环境变量

// 读取系统属性（-D 参数）
val jvmTarget = System.getProperty("jvmTarget", "17")

// 读取环境变量
val apiKey = System.getenv("API_KEY") ?: error("API_KEY 环境变量未设置")

// Gradle 推荐方式（懒加载）
val apiKeyProvider = providers.environmentVariable("API_KEY")
val jvmTargetProvider = providers.systemProperty("jvmTarget").orElse("17")

属性优先级

Gradle 属性按以下优先级从高到低解析：

1. 命令行 -P 参数
2. 系统属性中以 org.gradle.project. 开头的属性
3. GRADLE_USER_HOME/gradle.properties（用户级）
4. 项目根目录 gradle.properties（项目级）
5. 子项目 gradle.properties

实用模式

版本管理

// build.gradle.kts（根项目）
object Versions {
    const val SPRING_BOOT = "3.2.0"
    const val JUNIT = "5.10.1"
    const val GUAVA = "32.0.1-jre"
}

// 使用
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web:${Versions.SPRING_BOOT}")
}

根据属性切换行为

val isCI = System.getenv("CI") != null

tasks.named<Test>("test") {
    if (isCI) {
        maxParallelForks = 4
    }
}

下一步

• gradle.properties 配置 - 深入了解配置文件
• 版本目录（Catalog） - 统一管理依赖版本的最佳实践