从 Gradle 5.x 升级到 6.0

自 Gradle 3.4 以来，Java 生态系统插件中不鼓励使用 compile 和 runtime 配置。

这些配置用于编译和运行 main 源集中的代码。其他源集也会创建类似的配置（例如，test 源集的 testCompile 和 testRuntime），也不应使用。应使用 implementation、api、compileOnly 和 runtimeOnly 配置声明依赖，并使用 compileClasspath 和 runtimeClasspath 配置解析依赖。请参阅 这些配置的关系。

uploadArchives 任务和 maven 插件已弃用。

用户应通过使用 maven-publish 或 ivy-publish 插件迁移到 Gradle 的 发布系统。这些插件自 Gradle 4.8 以来一直稳定。

发布系统也是确保发布 Gradle Module Metadata 的唯一方式。

当 Gradle 检测到任务定义存在问题（例如输入或输出定义不正确）时，它会在控制台上显示以下消息

无论使用何种命令行开关，每次构建都会在 构建扫描 中显示弃用警告。

当构建使用 --warning-mode all 执行时，将显示各个警告

如果您拥有相关任务的代码，您可以通过遵循建议来修复它们。您还可以使用 --stacktrace 来查看每个警告源自代码的何处。

否则，您需要向相关任务或插件的维护者报告问题。

在 Gradle 5.4 中，我们引入了一个新的 API 来实现 增量任务：InputChanges。基于 IncrementalTaskInputs 的旧 API 已弃用。

使用 force = true 在一级依赖项上强制依赖版本已弃用。

强制存在语义和排序问题，可以通过使用 严格版本约束 来避免。

在 Gradle 5.0 中，我们移除了 --no-search-upward CLI 参数。

StartParameter 中相关的 API（如 isSearchUpwards()）现在已弃用。

这些方法目前无法按预期工作，因为回调在构建启动后永远不会被调用。

这些方法被弃用是为了避免混淆。

归档任务 Tar 和 Zip 默认允许在创建的归档中存在同一路径的多个条目。这可能导致 “严重无效的 zip 文件”，这可能触发 zip 炸弹检测。

为了防止这种情况意外发生，在创建归档时遇到重复现在会生成弃用消息，并将在 Gradle 7.0 开始使构建失败。

Copy 任务也乐意将具有相同相对路径的多个源复制到目标目录。此行为也已弃用。

如果您想允许重复，可以显式指定

Gradle 构建由当前或父目录中的 settings.gradle[.kts] 文件定义。如果没有 settings 文件，Gradle 构建将未定义并会发出弃用警告。

在 Gradle 7.0 中，Gradle 将只允许您在未定义的构建中调用 init 任务或诊断命令行标志，例如 --version。

一旦项目被评估，Gradle 将忽略传递给 Project#afterEvaluate 的所有配置，并发出弃用警告。此场景将在 Gradle 7.0 中成为错误。

以下捆绑插件从未发布，并将在 Gradle 的下一个主要版本中移除

其中一些插件可能在 插件门户 上有替代品。

Gradle 6.0 支持 Android Gradle Plugin 3.4 及更高版本。

对于 Gradle 6，Build Scan 插件的使用必须替换为 Develocity 插件。这还需要更改插件的应用方式。有关更多信息，请参阅 https://gradle.com/help/gradle-6-build-scan-plugin。

以前，Gradle 使用根项目名称作为包含构建的构建名称。现在，使用构建根目录的名称，如果根项目名称不同，则不考虑。如果通过 settings 文件包含构建，则可以为构建指定不同的名称。

以前的行为存在问题，因为它导致在构建的不同时间使用不同的名称。

以前，Gradle 不会阻止将“buildSrc”名称用于多项目构建的子项目或作为包含构建的名称。现在，这是不允许的。“buildSrc”名称现在保留给用于构建额外构建逻辑的传统 buildSrc 项目。

buildSrc 的典型使用不受此更改的影响。只有当您的 settings 文件指定 include("buildSrc") 或 includeBuild("buildSrc") 时，您才会受到影响。

Zinc 编译器已升级到版本 1.3.0。Gradle 不再支持为 Scala 2.9 构建。

Gradle 支持的最低 Zinc 编译器版本为 1.2.0，测试的最高版本为 1.3.0。

为了更容易选择 Zinc 编译器版本，您现在可以配置 zincVersion 属性

请移除您已添加到 zinc 配置的任何显式依赖项，并改为使用此属性。如果您尝试使用 com.typesafe.zinc:zinc 依赖项，Gradle 将切换到新的 Zinc 实现。

过去，可以将任何构建缓存实现用作 local 缓存。现在不再允许这样做，因为本地缓存必须始终是 DirectoryBuildCache。

调用 BuildCacheConfiguration.local(Class) 时，如果类型不是 DirectoryBuildCache，则将导致构建失败。使用 DirectoryBuildCache 类型调用这些方法将生成弃用警告。

请改用 getLocal() 和 local(Action)。

过去，当 Gradle 在打包缓存任务的结果时遇到问题，Gradle 会忽略问题并继续运行构建。

当遇到损坏的缓存工件时，Gradle 会移除已解包的内容，并重新执行任务以确保构建有机会成功。

虽然此行为旨在使构建成功，但它产生了隐藏问题的不利影响，并导致缓存性能下降。

在 Gradle 6.0 中，打包和解包错误都将导致构建失败，以便更容易地发现这些问题。

以前，为了在 buildSrc 构建中使用构建缓存，您需要在 buildSrc 构建中复制构建缓存配置。现在，它会自动使用顶层 settings 脚本定义的构建缓存配置。

Gradle Module Metadata 于 Gradle 5.3 正式引入，旨在解决多年来一直困扰依赖管理的许多问题，尤其是在 Java 生态系统中，但不仅限于此。

在 Gradle 6.0 中，Gradle Module Metadata 默认启用。

这意味着，如果您使用 Gradle 发布库并使用 maven-publish 或 ivy-publish 插件，Gradle Module Metadata 文件总是随传统元数据**一起发布**。

传统元数据文件将包含一个标记，以便 Gradle 知道有额外的元数据可供使用。

发布 Gradle Module Metadata 时会验证以下规则

这些也记录在 规范 中。

如果 Gradle 无法在 repositories { } 部分定义的仓库中找到模块的元数据文件（.pom 或 ivy.xml），它现在假定该模块在该仓库中不存在。

对于动态版本，相应的模块的 maven-metadata.xml 需要存在于 Maven 仓库中。

以前，Gradle 还会查找默认工件（.jar）。此行为在使用多个仓库时通常会导致大量不必要的请求，从而减慢构建速度。

您可以通过添加 artifact() 元数据源 来选择为选定的仓库恢复旧行为。

以前，如果 pom 打包不是 jar、ejb、bundle 或 maven-plugin，发布到 Maven 仓库的主工件的扩展名在发布期间会更改以匹配 pom 打包。

此行为导致 Gradle Module Metadata 损坏，并且由于处理不同的打包类型而难以理解。

构建作者可以在创建工件时更改工件名称以获得与以前相同的结果——例如，通过显式设置 jar.archiveExtension.set(pomPackaging)。

对 ivy-publish 插件中的 ivy.xml 元数据进行了许多修复，以生成更正确的元数据。

因此，ivy.xml 文件的内部结构发生了变化。runtime 配置现在包含更多信息，这与 Java 库的 runtimeElements 变体相对应。default 配置应产生与以前相同的结果。

通常，建议用户从 ivy.xml 迁移到新的 Gradle Module Metadata 格式。

以前，buildSrc 项目在应用项目设置脚本之前构建，并且其类在脚本中可见。现在，buildSrc 在设置脚本之后构建，其类对设置脚本不可见。buildSrc 类对项目构建脚本和脚本插件仍然可见。

自定义逻辑可以通过声明外部依赖项在设置脚本中使用。

以前，settings 脚本中的任何 pluginManagement {} 块都在脚本的正常执行期间执行。

现在，它们在早期以与 buildscript {} 或 plugins {} 类似的方式执行。这意味着此块中的代码不能引用脚本中其他地方声明的任何内容。

进行此更改是为了使 pluginManagement 配置在解析 settings 脚本本身的插件时也可以应用。

以前，通过使用 buildscript {} 添加到 settings 脚本的任何类在脚本外部都不可见。现在，它们对所有项目构建脚本都可见。

它们也对 buildSrc 构建脚本及其 settings 脚本可见。

进行此更改是为了使应用于 settings 脚本的插件能够为整个构建贡献逻辑。

与使用 kotlin-dsl 插件一样，如果您应用 embedded-kotlin 插件，现在需要声明一个可以找到 Kotlin 依赖项的仓库。

使用 1.3.50 之前的 Kotlin IntelliJ 插件版本时，如果 Gradle JVM 设置为与 Project SDK 不同的版本，Kotlin DSL 脚本将错误地高亮显示。只需将您的 IDE 插件升级到 >= 1.3.50 版本即可恢复正确的 Kotlin DSL 脚本高亮显示行为。

在以前的版本中，Kotlin DSL 脚本被编译成实现三个核心 Gradle 配置接口之一的类，以便隐式地将其 API 暴露给脚本。项目脚本的 org.gradle.api.Project，settings 脚本的 org.gradle.api.initialization.Settings，以及 init 脚本的 org.gradle.api.invocation.Gradle。

让脚本实例实现它应该配置的模型对象的 Gradle 核心接口很方便，因为它使模型对象 API 立即可用于脚本主体，但这也是一个谎言，当脚本本身被用作模型对象的替代品时，可能会导致各种麻烦。一个项目脚本**不是**一个真正的 Project 实例，仅仅因为它实现了核心 Project 接口，settings 和 init 脚本也是如此。

在 6.0 中，所有 Kotlin DSL 脚本都被编译成实现新引入的 org.gradle.kotlin.dsl.KotlinScript 接口的类，并且相应的模型对象现在作为**隐式接收者**在脚本主体中可用。换句话说，一个项目脚本的行为就好像脚本主体被包含在 with(project) { …​ } 块中，一个 settings 脚本的行为就好像脚本主体被包含在 with(settings) { …​ } 块中，一个 init 脚本的行为就好像脚本主体被包含在 with(gradle) { …​ } 块中。这意味着相应的模型对象也作为属性在脚本主体中可用，项目脚本的 project 属性，settings 脚本的 settings 属性，以及 init 脚本的 gradle 属性。

作为更改的一部分，SettingsScriptApi 接口不再由 settings 脚本实现，InitScriptApi 接口不再由 init 脚本实现。它们应该被替换为相应的模型对象接口，Settings 和 Gradle。

生成文档中的时间戳的实际用途非常有限，但是它们使得无法进行可重复的文档构建。因此，Javadoc 和 Groovydoc 任务现在默认配置为不再包含时间戳。

Gradle 总是使用 configDirectory 作为“config_loc”的值来运行 Checkstyle。

在 Gradle 6.0 中，我们引入了一个新的进度事件 (org.gradle.tooling.events.test.TestOutputEvent) 来公开测试执行的输出。这个新事件打破了拥有 StartEvent-FinishEvent 对来表达进度的约定。TaskOutputEvent 是一个简单的 ProgressEvent。

任务容器上的以下已弃用方法现在会导致错误

此外，以下已弃用功能现在会导致错误

请改用 ObjectFactory.fileProperty() 代替以下已移除的方法

请改用 ObjectFactory.directoryProperty() 代替以下已移除的方法

org.gradle.api.Nullable 注解类型已移除。请改用 JSR-305 的 javax.annotation.Nullable。

已弃用的 FindBugs 插件已移除。作为替代方案，您可以使用 Gradle 插件门户 中的 SpotBugs 插件。

已弃用的 JDepend 插件已移除。Gradle 插件门户 上提供了许多社区提供的代码和架构分析插件。

已弃用的 OSGI 插件已移除。Gradle 插件门户 上提供了许多社区提供的 OSGI 插件。

已弃用的 announce 和 build-announcements 插件已移除。Gradle 插件门户 上提供了许多社区提供的用于发送通知的插件。

已弃用的 Compare Gradle Builds 插件已移除。请使用 构建扫描 进行构建分析和比较。

已弃用的 Play 插件已移除。插件门户提供了外部替代品 Play Framework 插件。

抽象方法 compile() 不再由 AbstractCompile 声明。

扩展 AbstractCompile 的任务可以实现自己的 @TaskAction 方法，名称可以自行选择。

它们也可以随意添加一个用 @TaskAction 注解的方法，并带一个 InputChanges 参数，而无需同时实现一个无参数的方法。

当任务属性的类型为 ConfigurableFileCollection 时，该属性引用的文件集合在任务开始执行后将忽略对其内容的更改。这有两个好处。首先，这可以防止在任务执行期间意外更改属性值，这可能导致 Gradle 最新检查和构建缓存查找使用与任务操作使用的值不同的值。其次，这提高了性能，因为 Gradle 可以计算一次值并缓存结果。

这将在 Gradle 6.0 中成为错误。

直接创建 SignOperation 实例现在已弃用。相反，应使用 SigningExtension 的方法来创建这些实例。

这将在 Gradle 6.0 中成为错误。

声明没有输出的 增量任务 现在已弃用。请声明文件输出或改用 TaskOutputs.upToDateWhen()。

这将在 Gradle 6.0 中成为错误。

WorkerExecutor.submit() 方法现在已弃用。现在应使用新的 noIsolation()、classLoaderIsolation() 和 processIsolation() 方法提交工作。有关使用这些方法的更多信息，请参阅 Worker API 部分。

WorkerExecutor.submit() 将在 Gradle 8.0 中移除。

以前，对于类型为 Property 的任务 @Input 属性，任务依赖项将被忽略。现在，这些依赖项将得到遵守，这样就可以将任务输出属性附加到任务 @Input 属性。

这可能会在任务依赖图谱中引入意外的循环，其中输出属性的值映射以生成输入属性的值。

以前，可以向 Task.dependsOn() 传递一个不代表任务输出的 Provider、Provider 或 Provider 实例。这些提供程序将被静默忽略。

这现在是一个错误，因为 Gradle 不知道如何构建非任务输出的文件。

请注意，仍然可以将 Task.dependsOn() 传递一个返回文件并代表任务输出的 Provider，例如 myTask.dependsOn(jar.archiveFile) 或 myTask.dependsOn(taskProvider.flatMap { it.outputDirectory })，当 Provider 是任务的带注解的 @OutputFile 或 @OutputDirectory 属性时。

以前，调用 Property.set(null) 总是会将属性值重置为“未定义”。现在，将使用与属性通过 convention() 方法关联的约定来确定属性的值。

仓库和发布名称用于构造发布任务名称。以前可以提供一个会导致无效任务名称的名称。现在，发布和仓库的名称被限制为 [A-Za-z0-9_\\-.]+。

Gradle 现在阻止内部依赖项（如 Guava）泄漏到 Worker API 操作使用的类路径中。这修复了 一个问题，即工作程序需要使用 Gradle 内部也使用的依赖项。

在以前的版本中，可以依赖这些泄漏的类。依赖此行为的插件现在将失败。要修复该插件，工作程序应在其类路径中显式包含所有必需的依赖项。

PMD 插件 已升级为默认使用 PMD 版本 6.15.0，而不是 6.8.0。

由 wreulicke 贡献

以前，配置的所有副本始终具有名称 Copy。现在，当创建多个副本时，每个副本都将通过添加从第二个副本开始的索引来拥有唯一名称。（例如 CompileOnlyCopy2）

Gradle 5.6 不再在 Eclipse 模型中提供自定义类路径属性。相反，它为 Eclipse 测试源 提供属性。此更改需要 Buildship 3.1.1 或更高版本。

现在使用 Kotlin 1.3.41 编译 Gradle Kotlin DSL 脚本和使用 kotlin-dsl 插件编写的 Gradle 插件。

有关包含更改的更多信息，请参阅 Kotlin 博客文章 和 变更日志。

支持的最低 Kotlin Gradle 插件版本现在是 1.2.31。以前是 1.2.21。

以前的 Gradle 版本在出现能力冲突时会自动选择具有最高能力版本的模块。从 5.6 开始，这是一种选择性行为，可以通过以下方式激活

有关更多选项，请参阅 文档的能力部分。

当 Gradle 因各种原因需要移除任务的输出文件时，它不会遵循符号链接目录。符号链接本身将被删除，但链接目录的内容将保持不变。

内置的 Play 插件 已弃用，将由插件门户提供的新 Play Framework 插件 取代。

构建比较插件已弃用，并将在 Gradle 的下一个主要版本中移除。

构建扫描 可以更深入地洞察您的构建，您可以使用 Develocity 直接比较两个构建的构建扫描。

通过 EclipseProject.setName(…​) 配置的项目名称在所有情况下都受到 Gradle 和 Buildship 的遵守，即使名称导致冲突和导入/同步错误。

如果这些名称与 Eclipse 工作区中的其他项目名称冲突，Gradle 现在可以对它们进行去重。这可能导致具有用户指定名称的项目使用不同的 Eclipse 项目名称。

即将发布的 Buildship 3.1.1 版本需要利用此行为。

由 Christian Fränkel 贡献

JaCoCo 插件 已升级为默认使用 JaCoCo 版本 0.8.4，而不是 0.8.3。

由 Evgeny Mandrikov 贡献

Gradle 分发的 Ant 版本已从 1.9.13 升级到 1.9.14。

这会影响使用 ExtensionAware 扩展成员（例如 dependencies {} 块中的 extra 属性访问器）的 Kotlin DSL 构建脚本。这些成员的接收者将不再是封闭的 Project 实例，而是 dependencies 对象本身，即最内层的符合 ExtensionAware 的接收者。为了在 dependencies {} 中处理 Project 额外属性，接收者必须显式限定，即 project.extra 而不是仅仅 extra。受影响的扩展还包括 the() 和 configure(T.() → Unit)。

以前的 Gradle 版本在某些复杂的依赖图谱中，如果存在大量排除项，可能会导致错误的结果或随机的依赖项顺序。为了缓解这个问题，计算排除项的算法已重写。在极少数情况下，这可能会由于正确性更改而导致解析结果出现一些差异。

在使用 PROCESS 隔离时，由 Worker API 启动的工作守护进程的系统类路径已减少到最少的 Gradle 基础设施集。用户代码仍然被隔离到一个单独的类加载器中，以将其与 Gradle 运行时隔离。这对于使用 worker API 的任务来说应该是一个透明的更改，但以前的 Gradle 版本会将用户代码和 Gradle 内部结构混合在工作进程中。依赖于 java.class.path 系统属性等的工作操作可能会受到影响，因为 java.class.path 现在只表示 Gradle 内部的类路径。

使用自定义构建缓存实现作为本地构建缓存现在已弃用。未来唯一允许的类型将是 DirectoryBuildCache。在将自定义构建缓存实现用作远程构建缓存的支持方面没有变化。

通过 JavaScriptRepositoriesExtension#GOOGLE_APIS_REPO_URL 可访问的 Google Hosted Libraries URL 已更改为使用 HTTPS 协议。此更改也影响通过 googleApis() 配置的 Ivy 仓库。

从 Gradle 5.0 到 5.2.1（包括）存在一个错误，即强制平台可能会包含依赖项而不是约束。当 POM 文件同时定义了依赖项和“约束”（通过 ）并且您使用了 enforcedPlatform 时，就会发生这种情况。Gradle 5.3 修复了此错误，这意味着如果您依赖此损坏的行为，则解析结果可能会有所不同。同样，Gradle 5.3 将不再尝试下载 platform 和 enforcedPlatform 依赖项的 jar（因为它们只应引入约束）。

如果您应用任何 Java 插件，Gradle 现在会尽力选择与要编译模块的目标兼容性匹配的依赖项。实际上，这意味着如果您的模块 A 是为 Java 8 构建的，模块 B 也是为 Java 8 构建的，那么没有变化。但是，如果 B 是为 Java 9+ 构建的，那么它就不再是二进制兼容的，Gradle 会抱怨并显示如下错误消息

通常，这表明您的项目配置错误，并且您的依赖项不兼容。但是，在某些情况下，您可能仍然希望这样做，例如，当您的模块中只有**一部分**类确实需要 Java 9 依赖项，并且不打算在早期版本上使用。Java 通常不鼓励您这样做（您应该拆分您的模块），但如果您遇到此问题，可以通过在消费者端禁用此新行为来解决

如果您有一个 Maven 依赖项指向一个 Ivy 依赖项，其中 default 配置依赖项与 compile + runtime + master 不匹配，并且该 Ivy 依赖项被替换了（使用 resolutionStrategy.force、resolutionStrategy.eachDependency 或 resolutionStrategy.dependencySubstitution），那么此修复将影响您。Gradle 5.0 之前的遗留行为仍然存在，而不是被改进的 pom 支持引入的更改所取代。

在 Windows 上，对于 clean 任务、所有 Delete 任务以及存在连接点和符号链接的 project.delete {} 操作，Gradle 不再忽略 followSymlink 选项。

在以前的 Gradle 版本中，项目级别注册的附加工件不会被 maven-publish 或 ivy-publish 发布，除非它们也作为工件添加到发布配置中。

在 Gradle 5.3 中，这些工件现在已正确核算并发布。

这意味着同时在项目和发布（Ivy 或 Maven）上注册的工件将导致发布失败，因为它会创建重复条目。修复方法是从发布配置中移除这些工件。

Sign 任务的输入和输出文件现在分别通过 Signature.getToSign() 和 Signature.getFile() 跟踪。

在 Gradle 5.0 中，使用 ObjectFactory 创建的集合属性实例将没有定义值，要求插件作者显式设置初始值。事实证明这很笨拙且容易出错，因此 ObjectFactory 现在返回初始值为空集合的实例。

由于 JDK 11 不再支持更改正在运行进程的工作目录，因此现在禁止通过其 fork 选项设置工作程序的工作目录。所有工作程序现在都使用相同的工作目录以启用重用。请改用参数传递文件和目录。请参阅 Worker API 文档 中的示例。

为了扩展我们惯用的 Provider API 实践，org.gradle.nativeplatform.tasks.LinkSharedLibrary 的安装名称属性受此更改的影响。

为了扩展我们惯用的 Provider API 实践，WindowsResourceCompile 任务已转换为使用 Provider API。

传递附加编译器参数现在遵循与 CppCompile 和其他任务相同的模式。

beforeResolve 操作列表不再在复制的配置和原始配置之间共享。相反，复制的配置在复制时接收 beforeResolve 操作的副本。复制后（添加到任一配置）添加的任何 beforeResolve 操作将不会在原始配置和副本之间共享。这可能会破坏依赖以前行为的插件。

原生组件上孵化中的 operatingSystems 属性已替换为 targetMachines 属性。