Gradle 发布说明

升级说明

通过更新项目中包装器，将您的构建切换到使用 Gradle 9.0.0

./gradlew wrapper --gradle-version=9.0.0 && ./gradlew wrapper

有关升级到 Gradle 9.0.0 时的弃用、重大更改和其他注意事项，请参阅Gradle 9.0.0 升级指南。

有关 Java、Groovy、Kotlin 和 Android 兼容性，请参阅完整兼容性说明。

新功能和可用性改进

配置缓存改进

Gradle 的配置缓存通过缓存和重用配置阶段的结果来提高构建性能。

配置缓存作为首选执行模式

配置缓存是首选的执行模式。虽然目前不是强制要求，但 Gradle 鼓励用户采用，并通过提示用户并逐步淘汰不兼容的 API 来为未来它成为唯一支持的模式做准备。

提示启用配置缓存

如果您的构建没有已知的配置缓存不兼容性但尚未启用配置缓存，Gradle 将在构建结束时建议启用它

有些问题只能在配置缓存处于活动状态时检测到，因此可能仍需要额外的调整才能完全采用它。

如果您尚未准备好为此投入时间，可以通过在 gradle.properties 文件中显式禁用该功能来抑制此建议

org.gradle.configuration-cache=false

从配置缓存模式优雅回退

当遇到不支持的功能时，Gradle 会自动回退到非配置缓存模式，而不是导致构建失败。

这包括

• 支持有限的核心插件（例如 Maven Publish 和 Ivy Publish）
• 不支持或不兼容的 IDE 插件（例如 Eclipse 和 IDEA）
• 尚未支持的功能（例如源依赖项）

运行构建后，回退原因可以在配置缓存报告中找到。

其他值得注意的配置缓存更新

配置缓存的其他更新包括

• 标记为不兼容的任务会阻止警告模式下的缓存命中，从而确保正确性。警告模式应仅在迁移或故障排除期间使用。将任务标记为不兼容仍然是逐步采用的推荐策略。
• 当遇到配置缓存问题时，任务执行将立即中止，从而避免未定义的行为并确保受影响的任务既未标记为最新也未缓存。
• 配置缓存报告包含更详细的错误，例如序列化问题、不安全的并发访问以及 Groovy DSL 闭包捕获脚本状态。

Gradle 运行需要 Java 虚拟机 (JVM) 版本 17 或更高版本

Gradle 需要 Java 虚拟机 (JVM) 版本 17 或更高版本才能启动 Gradle 守护进程。

如果您需要使用旧版 JVM 进行构建，可以通过使用工具链在构建定义中指定单独的 JDK 工具链。
Gradle 仍然支持使用 Java 8 及更高版本编译、测试和运行其他基于 JVM 的工具。

更多信息请参阅兼容性矩阵。

更新到 Kotlin 2

Gradle 嵌入了Kotlin 2.2.x 运行时的最新稳定版本，并使用Kotlin 语言版本 2.2。这标志着与 Gradle 8.x 的转变，Gradle 8.x 从 8.11 开始嵌入了 Kotlin 2.0，但为了兼容性继续使用 Kotlin 语言版本 1.8。

有关新特性的全面概述，请参阅Kotlin 2.2.0、Kotlin 2.1.0 和Kotlin 2.0.0 发布说明。

Gradle 使用 Kotlin 进行构建逻辑，其中包括

• 用 Kotlin DSL 编写的构建脚本（.gradle.kts 文件）
• 插件

因此，一些行为发生了变化，最值得注意的是新的 K2 编译器和API 上的可空性注解。如果您正在升级，请查看Gradle 9.0.0 升级指南以获取迁移详情。

更新到 Groovy 4

Gradle 嵌入了Groovy 4.0 的最新稳定版本，这是对 Gradle 7 和 8 中使用的 Groovy 3.0 版本的重大升级。

此更新引入了 Groovy 语言的一系列新功能和改进。有关新功能的全面概述，请参阅Groovy 4.0 发布说明以获取完整详情。

Gradle 使用 Groovy 进行构建逻辑，其中包括

• 用 Groovy DSL 编写的构建脚本（.gradle 文件）
• Ant 集成
• 插件

Groovy 3.0 和 4.0 之间的一些行为有所改变。如果您正在升级，请查看Gradle 9.0.0 升级指南以获取迁移详情。

Gradle 发布的语义版本控制

从 Gradle 9 开始，所有 Gradle 版本都遵循语义版本控制 (SemVer) 规范。

版本号表示为 MAJOR.MINOR.PATCH，而以前的次要版本省略了补丁段（例如，8.5 而不是 8.5.0）。

此更改仅适用于新版本，不追溯影响旧版本或向后移植。此外，内部代码和标记为 @Incubating 的功能不被视为公共 API 的一部分，并且可能在次要版本中发生更改。

构建作者改进

Gradle 为插件作者和构建工程师提供丰富的 API，用于开发自定义构建逻辑。

Kotlin 构建脚本编译规避

Gradle 通过避免不必要的Kotlin DSL (.kts) 构建脚本重新编译，加快了编辑构建逻辑时的反馈循环。这缩短了构建时间并提高了开发人员的生产力。

这一改进得益于对 ABI（应用程序二进制接口）变化的显著改进的检测，这通过使用 Kotlin 内置的 ABI 指纹识别而不是 Gradle 以前的内部机制而实现。这带来了主要的性能优势，尤其是在使用内联函数的构建中，之前这些函数没有得到有效处理。

例如，在 Gradle 构建本身中，对构建逻辑的非 ABI 更改通过避免不必要的脚本重新编译，配置时间最多可减少 60%。

Gradle API 使用 JSpecify 可空性注解

自 Gradle 5.0 以来，我们一直使用 JSR-305 的注解来明确 Gradle API 中类型使用的可空性。从 Gradle 9 开始，Gradle API 转而使用 JSpecify 进行注解。

Kotlin 2.1 与 Gradle API 中的 JSpecify 注解结合使用，引入了更严格的可空性处理。有关更多详细信息和潜在的破坏性更改，请参阅专门的升级指南章节。

Gradle Wrapper 中对主次版本规范的支持

Gradle 支持在配置包装器时仅指定主版本或次版本。

例如，以下解析为最新的 9.x.y 版本

./gradlew wrapper --gradle-version=9

而以下解析为最新的 9.1.x 版本

./gradlew wrapper --gradle-version=9.1

此功能需要 Gradle 9.0.0 或更高版本。早期版本不遵循完整的语义版本控制，并且可能错误地解释部分版本（例如，8.12 可能指 8.12（因为它是精确版本）和 8.12.1（语义上是 8.12 的最新版本）。

Gradle 的版本信息端点已扩展以支持此行为。例如，https://services.gradle.org/versions/9 列出了所有主版本为 9 的 Gradle 版本。

归档任务默认生成可重现的归档文件

Jar、Ear、War、Zip、Tar 和 AbstractArchiveTask 等归档任务默认生成可重现的归档文件。这意味着生成的归档文件具有可重现的文件顺序和预配置的文件时间戳和权限。因此，由相同输入生成的归档文件将逐字节相同。

此更改可能会影响依赖于非确定性归档特性（如文件顺序、文件系统时间戳或文件系统权限，或文件可执行位）的构建。

更多信息，请参阅升级指南章节。

分离配置可以解析对自身项目的依赖项

分离配置能够解析引用自身项目的依赖项。

为此，Gradle 引入了 ComponentIdentifier 的新子类型，名为 RootComponentIdentifier，它表示已解析依赖关系图的根节点。

当配置解析时，它首先被转换为合成变体。此变体由合成根组件拥有，该根组件使用 RootComponentIdentifier 标识。根组件本身仅用于拥有根变体。

从分离配置和 buildscript 配置解析的依赖关系图将在其图的根部有一个由 RootComponentIdentifier 标识的组件。这使得 Gradle 能够区分分离配置及其所在的 project。

已解析的项目配置将继续将其根组件包含在项目组件中，并由 ProjectComponentIdentifier 标识。在未来的 Gradle 版本中，所有配置（包括在项目中声明的配置（非分离））都将由一个由 RootComponentIdentifier 标识的合成根组件拥有。

JAVA_HOME 环境变量用于工具链自动检测

Gradle 的工具链支持允许为构建项目（编译代码、运行测试甚至运行 Gradle 本身）提供和选择特定 JDK 版本。

此版本增加了对使用 JAVA_HOME 环境变量作为工具链自动检测源的支持。此更改提高了从命令行检测到的工具链与 IDE 检测到的工具链之间的一致性，因为 IDE 以前不考虑 JAVA_HOME。

文档改进

Gradle 最佳实践

我们与 JetBrains 和 Google 合作，推出了新的Gradle 最佳实践指南，旨在帮助您避免常见陷阱，编写更易于维护、性能更好的构建。这些建议将社区知识和 Gradle 团队的见解整合到一个不断增长的资源中。当前版本涵盖了依赖声明、构建结构、任务编写等方面的最佳实践。

更多信息，请查阅Gradle 最佳实践博客文章。

升级功能

升级功能是指在 Gradle 以前版本中处于孵化阶段但现在受支持并受向后兼容性约束的功能。有关更多信息，请参阅用户手册中“功能生命周期”部分。

以下是本次 Gradle 版本中已升级的功能。

Kotlin DSL 中升级的功能

DependencyHandlerScope 中的以下运算符函数被认为是稳定的

• NamedDomainObjectProvider<Configuration>.invoke(dependencyNotation: Any): Dependency?
• NamedDomainObjectProvider<Configuration>.invoke(dependencyNotation: String, dependencyConfiguration: ExternalModuleDependency.() -> Unit): ExternalModuleDependency
• NamedDomainObjectProvider<Configuration>.invoke(group: String, name: String, version: String?, configuration: String?, classifier: String?, ext: String?): ExternalModuleDependency
• NamedDomainObjectProvider<Configuration>.invoke(group: String, name: String, version: String?, configuration: String?, classifier: String?, ext: String?, dependencyConfiguration: ExternalModuleDependency.() -> Unit): ExternalModuleDependency
• <T : Any> Configuration.invoke(dependency: Provider<T>, dependencyConfiguration: ExternalModuleDependency.() -> Unit)
• <T : Any> Configuration.invoke(dependency: ProviderConvertible<T>, dependencyConfiguration: ExternalModuleDependency.() -> Unit)
• <T : Any> NamedDomainObjectProvider<Configuration>.invoke(dependency: Provider<T>)
• <T : Any> NamedDomainObjectProvider<Configuration>.invoke(dependency: ProviderConvertible<T>)
• <T : Any> NamedDomainObjectProvider<Configuration>.invoke(dependency: Provider<T>, dependencyConfiguration: ExternalModuleDependency.() -> Unit)
• <T : Any> NamedDomainObjectProvider<Configuration>.invoke(dependency: ProviderConvertible<T>, dependencyConfiguration: ExternalModuleDependency.() -> Unit)
• <T : Any> String.invoke(dependency: Provider<T>, dependencyConfiguration: ExternalModuleDependency.() -> Unit)
• <T : Any> String.invoke(dependency: ProviderConvertible<T>, dependencyConfiguration: ExternalModuleDependency.() -> Unit)
• <T : ModuleDependency> NamedDomainObjectProvider<Configuration>.invoke(dependency: T, dependencyConfiguration: T.() -> Unit): T

DependencyConstraintHandlerScope 中的以下运算符函数被认为是稳定的

• NamedDomainObjectProvider<Configuration>.invoke(dependencyConstraintNotation: Any): DependencyConstraint
• NamedDomainObjectProvider<Configuration>.invoke(dependencyConstraintNotation: String, configuration: DependencyConstraint.() -> Unit): DependencyConstraint

DependencyHandlerExtensions 中的以下顶级函数被认为是稳定的

• DependencyHandler.create(dependencyNotation: String, dependencyConfiguration: ExternalModuleDependency.() -> Unit): ExternalModuleDependency

KotlinDependencyExtensions 中的以下顶级函数被认为是稳定的

• PluginDependenciesSpec.embeddedKotlin(module: String): PluginDependencySpec

以下函数被认为是稳定的

• GroovyBuilderScope.hasProperty(name: String): Boolean

已解决问题

已知问题

已知问题是指在发布后发现的与此版本所做更改直接相关的问题。

外部贡献

我们乐于接受 Gradle 社区的贡献。有关贡献的信息，请参阅gradle.org/contribute。

报告问题

如果您发现此版本有问题，请根据我们的问题指南在GitHub Issues上提交错误。如果您不确定是否遇到错误，请使用论坛。

我们希望您能用 Gradle 构建出幸福，我们期待您通过Twitter或GitHub提供反馈。