将构建从 Gradle 6.x 升级到 7.0

和getGeneratedSourceDirectories()方法getGeneratedTestDirectories()已从IdeaContentRoot接口中删除。客户端应将这些调用替换为getSourceDirectories()and并在返回的实例上getTestDirectories()使用该方法。isGenerated()

由于 Groovy 的下一个主要版本的更新，您在升级到 Gradle 7.0 时可能会遇到小问题。

新版本的 Groovy 有一个更严格的解析器，无法编译以前的 Groovy 版本中可能已接受的代码。如果遇到语法错误，请检查Groovy 问题跟踪器和Groovy 3 发布亮点。

一些非常具体的回归已经在 Groovy 的下一个小版本中得到修复。

自诞生以来，Gradle 提供了compile和runtime配置来声明依赖项。然而，这些不支持细粒度的依赖关系范围。因此，Gradle 3.4 中引入了更好的替代品：

在 Gradle 7 中，compile和runtime配置都被删除。因此，您必须迁移到上面的implementation配置api。如果您仍在使用javaJava 库的插件，则需要java-library改为应用该插件。

您可以通过阅读Java 库插件文档找到有关新配置的优点以及使用哪一种配置来代替的更多详细compile信息。runtime

该ProjectBuilderAPI 用于检查单元测试中的 Gradle 构建。该API用于在系统临时目录下创建临时项目文件，如java.io.tmpdir.

API 现在会在Test任务的临时目录下创建临时项目文件。该路径通常位于项目构建目录下。当测试需要特定文件路径时，这可能会导致测试失败。

如果测试使用ProjectBuilder.withProjectDir(…​)，则不受影响。

使用TestKit API的测试用于在系统临时目录下创建临时文件，如java.io.tmpdir.这些文件用于存储 Gradle 发行版或另一个仅供测试的 Gradle 用户主页的副本。

TestKit 测试现在将在Test任务的临时目录下创建临时文件。该路径通常位于项目构建目录下。当测试需要特定文件路径时，这可能会导致测试失败。

如果测试使用GradleRunner.withTestKitDir(…​)，则不受影响。

Windows 上的文件系统监视实现向根项目目录添加了锁，以便监视更改。当您在使用 TestKit 运行构建后尝试删除根项目目录时，这可能会导致错误。例如，使用 TestKit 与 JUnit@TempDir扩展或TemporaryFolder规则一起进行的测试可能会遇到此问题。为了避免这些文件锁出现问题，TestKit请禁用文件系统监视在 Windows 上通过GradleRunner.如果您想覆盖默认行为，可以通过传递--watch-fs到 来启用文件系统监视GradleRunner.withArguments()。

该maven插件已被删除。您应该改用该maven-publish插件。

更多详细信息请参阅Maven Publish 插件的文档。

该uploadArchives任务与遗留的 Ivy 或 Maven 发布机制结合使用。它已在 Gradle 7 中删除。您应该迁移到maven-publish或ivy-publish插件。

请参阅Maven Publish 插件的文档以在 Maven 存储库上发布。请参阅Ivy Publish 插件的文档以在 Ivy 存储库上进行发布。

在依赖版本排序的上下文中，-SNAPSHOT版本现在被认为是在最终版本之前但在任何-RC版本之后。还考虑了更多特殊版本后缀。对于众所周知的版本后缀，这使得 Gradle 算法更接近 Maven 算法。

查看Gradle 适用的所有规则的文档。

已弃用的 Play 插件已被删除。可以从插件门户获取外部替代品Play Framework 插件。

以下用于实验性 JavaScript 集成的插件现已从发行版中删除： coffeescript-base, envjs, javascript-base, jshint, rhino。

如果您使用这些插件（尽管它们是实验性的），您可以在插件门户中找到合适的替代品。

采用配置块的方法已被删除，并被patternLayoutlayout取代。

settings.gradle(.kts)Gradle 构建由当前目录或父目录中的文件定义。如果没有设置文件，Gradle 构建是未定义的，并且 Gradle 在尝试执行任务时会产生错误。

要修复此错误，请为构建创建一个settings.gradle(.kts)文件。

例外情况是通过init任务调用 Gradle 或使用诊断命令行标志，例如--version.

Gradle 6.x 会警告用户有关错误行为，并忽略这种情况下的目标操作。从7.0开始，同样的情况会产生错误。插件和构建脚本应调整为afterEvaluate仅在配置时调用。如果您遇到这样的构建失败并且相关afterEvaluate语句已在构建源中声明，那么您只需将其删除即可。如果afterEvaluate在插件中声明，则将问题报告给插件维护者。

请改用ObjectFactory#fileCollection()。

请改用libsDirectory和distsDirectory属性。

现有用法应替换为RuntimeException.

和getBaseName()方法setBaseName()已从类中删除Distribution。客户应将用途替换为distributionBaseName属性。

AbstractTask使用类型或类型扩展注册任务AbstractTask在 Gradle 6.5 中已被弃用，现在在 Gradle 7.0 中是一个错误。您可以使用DefaultTask代替。

BuildListener.buildStarted(Gradle)在 Gradle 6.0 中已弃用，现已在 Gradle 7.0 中删除。请改用BuildListener.beforeSettings(Settings)。

自 Gradle 5.0 起，以下 API 不再可通过命令行选项使用，现已删除 ：StartParameter.useEmptySettings()、StartParameter.isUseEmptySettings()和。StartParameter.setSearchUpwards(boolean)StartParameter.isSearchUpwards()

Gradle 不再支持在master同级目录中指定的目录中发现设置文件。如果您的构建仍然使用此已弃用的功能，请考虑重构构建以使根目录与项目层次结构的物理根匹配。您可以在用户手册中找到有关如何构建 Gradle 构建或构建组合的master更多信息。或者，您仍然可以通过仅使用 任务的完全限定路径从目录调用构建来运行这样的构建中的任务。

现在，对于通过包含文件定义模块的任何源集，编译、 测试和 执行module-info.java都会自动进行。通常，这是您需要的行为。如果这在您手动配置模块路径或使用第三方插件时导致问题，您仍然可以通过在 java 扩展或单个任务上modularity.inferModulePath设置为来选择退出。false

该ValidateTaskProperties任务已被删除并由ValidatePlugins任务取代。

该ImmutableFileCollection类型已被删除。请改用工厂方法。可以通过Project.layout获取项目布局的句柄。

该方法ComponentSelectionReason.getDescription已被删除。它被替换为ComponentSelectionReason.getDescriptions返回一个 列表ComponentSelectionDescriptor，每个列表都有一个getDescription。

以下已弃用的构造函数已被删除：

本地构建缓存配置现在需要通过BuildCacheConfiguration.local()完成。

这个内部 API 在Nebula 插件等插件中使用，在 Gradle 5.x 时间线中已弃用，现已删除。最新的插件版本不应再引用它。

该checkstyle插件现在无法执行以下配置

构建应使用块声明 checkstyle 配置checkstyle：

Gradle 6.x 警告用户错误行为，然后返回可能不正确的提供程序值。从 7.0 开始，相同的情况将产生错误。任务完成后，应调整插件和构建脚本以查询提供程序的映射值，例如任务输出属性。

Gradle 6.0 开始警告有关任务定义的问题（例如错误定义的输入或输出）。对于 Gradle 7.0，这些警告现在是错误，并且会使构建失败。

以前的 Gradle 版本在特定配置中的冲突解决方面存在不一致的行为： - 您的项目声明了对已发布模块的严格依赖（例如，com.mycompany:some-module:1.2!!，其中1.2!!是严格依赖于 1.2 的简写符号） - 您的构建实际上com.mycompany:some-module更高版本提供

以前的 Gradle 版本会成功，尽管有严格的限制，但仍会选择项目依赖项。从 Gradle 7 开始，这将触发依赖解析失败。

请参阅此问题了解更多背景信息。

不推荐使用在某个位置产生输出的任务和通过将其引用为输入来消耗该位置的另一个任务，而无需依赖于生产者任务的消费者任务。解决此问题的方法是添加从消费者到生产者的依赖关系。

现在，当复制操作（或任何使用 的操作org.gradle.api.file.CopySpec）遇到重复条目并且未设置重复策略时，Gradle 7 会失败。请查看CopySpec 文档了解详细信息。

支持 Java 工具链功能的 APIorg.gradle.jvm.toolchain现在标记为@NonNull。

这可能会影响 Kotlin 使用者，因为 API 的返回类型不再可为空。

以前，Eclipse 导入的项目仅包含主源集和测试源集的依赖项。自定义源集的编译和运行时类路径被忽略。

从 Gradle 6.8 开始，导入到 Eclipse 中的项目包括构建定义的每个源集的编译和运行时类路径。

以前，在最新检查和为 中声明的源构建缓存键计算期间将考虑空目录SourceTask。这意味着包含空目录的源树和不包含空目录的其他相同源树将被视为不同的源，即使任务会产生相同的输出。在 Gradle 6.8 中，SourceTask现在在执行最新检查和构建缓存键计算期间忽略空目录。在绝大多数情况下，这是所需的行为，但当SourceTask源中存在空目录时，任务可能会扩展，但也会产生不同的输出。对于需要关注的任务，您可以公开一个不带@IgnoreEmptyDirectories注释的单独属性，以捕获这些更改：

现在，发布依赖于强制平台的组件会触发验证错误，从而防止意外发布错误的元数据：强制平台用例应仅限于应用程序，而不是可以从其他库或应用程序使用的内容。

如果出于某种原因，您仍然希望发布依赖于强制平台的组件，您可以按照文档禁用验证。

为了方便起见，Gradle 的文件树应用了一些默认的排除模式 — 事实上与 Ant 的默认值相同。请参阅用户手册了解更多信息。有时，Ant 的默认排除被证明是有问题的，例如当您想要将 包含.gitignore在存档文件中时。

在执行阶段更改 Gradle 的默认排除可能会导致最新检查的正确性问题。因此，您只能在设置脚本中更改 Gradle 的默认排除项，请参阅用户手册以获取示例。

不推荐直接引用 中包含的构建中的任务mustRunAfter，shouldRunAfter并且finalizedBy任务方法已被弃用。任务排序使用mustRunAfter和 以及shouldRunAfter由 指定的终结器finalizedBy应该用于构建内的任务排序。如果您碰巧使用上述方法定义了交叉构建任务顺序，请考虑重组此类构建并将它们相互解耦。

master当您的构建依赖于在同级目录中指定的目录中查找设置文件时，Gradle 将发出弃用警告。

如果您的构建使用此功能，请考虑重构构建以使根目录与项目层次结构的物理根匹配。

master或者，您仍然可以通过仅使用 任务的完全限定路径从目录调用构建来运行这样的构建中的任务。

Gradle Kotlin DSL 扩展已更改为更倾向于 GradleAction<T>类型而不是 Kotlin 函数类型。

虽然更改对于 Kotlin 客户端来说应该是透明的，但调用 Kotlin DSL 扩展的 Java 客户端需要更新才能使用 API Action<T>。

以前，buildSrc构建方式是从根构建中忽略包含的构建。

从 Gradle 6.7 开始，buildSrc可以从根构建中查看任何包含的构建。这可能会导致依赖项被包含的构建替换buildSrc。如果buildSrc.

为了方便起见，Gradle 的文件树应用了一些默认的排除模式 — 事实上与 Ant 的默认值相同。请参阅用户手册了解更多信息。有时，Ant 的默认排除被证明是有问题的，例如当您想要将 包含.gitignore在存档文件中时。

在执行阶段更改 Gradle 的默认排除可能会导致最新检查的正确性问题，因此已被弃用。您只能在设置脚本中更改 Gradle 的默认排除，有关示例，请参阅用户手册。

ConfigurationGradle 允许直接使用的实例作为依赖项：

这种行为现在已被弃用，因为它令人困惑：人们可能期望首先解析“依赖配置”，并将解析结果作为依赖项添加到包含配置中，但事实并非如此。已弃用的版本可以替换为实际行为，即配置继承：

在添加对依赖项替换中表达变体支持的支持时，错误修复引入了某些构建可能依赖的行为更改。以前，替换的依赖项仍将使用原始选择器的属性，而不是替换选择器中的属性。

随着这一变化，现有的依赖项与更丰富的选择器的替代（例如平台依赖项）将不再像以前那样工作。必须在目标选择器中定义变体感知部分。

如果您符合以下条件，您可能会受到此更改的影响：

如果您受到影响，请参阅文档以解决问题。

AbstractTask是一个内部类，在公共 API 上可见，作为公共类型的超类DefaultTask。 AbstractTask将在 Gradle 7.0 中删除，并且以下内容在 Gradle 6.5 中已弃用：

Gradle 6.4 默认启用增量分析。增量分析仅在 PMD 6.0.0 或更高版本中可用。如果你想使用旧的PMD版本，你需要禁用增量分析：

在 Gradle 6.4 中，依赖锁定LockMode的孵化 API发生了变化。该值现在通过 aProperty<LockMode>而不是直接设置器设置。这意味着必须为 Kotlin DSL 更新设置值的表示法：

Groovy DSL 的用户不应受到影响，因为该符号lockMode = LockMode.STRICT仍然有效。

如果 Java 库是使用 Gradle 模块元数据发布的，则其支持的 Java 版本信息将编码在org.gradle.jvm.version属性中。默认情况下，此属性设置为您在 中配置的内容java.targetCompatibility。如果未配置，则将其设置为运行 Gradle 的当前 Java 版本。例如，更改特定编译任务的版本javaCompile.targetCompatibility对该属性没有影响，如果未手动调整该属性，则会导致错误信息。现在此问题已修复，并且该属性默认为与构建已发布 jar 的源关联的编译任务的设置。

在具有自定义存储库布局的 Ivy 存储库上发布时，包含的 Gradle 版本从 6.0 到 6.3.x 可能会生成错误的 Gradle 模块元数据。从 6.4 开始，如果 Gradle 检测到您正在使用自定义存储库布局，它将不再发布 Gradle 模块元数据。

此版本  在不同的地方引入了一些新属性 - mainClass、mainModule、 -。modularity由于这些是非常通用的名称，因此您有可能在构建脚本中使用其中之一作为变量名称。然后，新属性可能会以不期望的方式隐藏变量之一，从而导致构建失败，即访问该属性而不是同名的局部变量。您可以通过重命名构建脚本中相应的变量来修复它。

受影响的是application {}和java {}配置块内的配置代码、使用 和 进行设置的 java 执行设置project.javaexec {}以及各种任务配置（JavaExec、CreateStartScripts、JavaCompile、Test、Javadoc）内的配置代码。

Gradle 不再包含注释处理器类路径作为 IDEA 中提供的依赖项。 IDEA 在编译时看到的依赖项与解析编译类路径（名为 的配置）后 Gradle 看到的依赖项相同compileClasspath。这可以防止注释处理器依赖项泄漏到项目代码中。

在Gradle引入增量注释处理支持之前，IDEA要求所有注释处理器都位于编译类路径上，以便在IDEA中编译时能够运行注释处理。这不再是必要的，因为 Gradle 有一个单独的注释处理器类路径。当导入带有注释处理器的 Gradle 项目时，注释处理器的依赖项不会添加到 IDEA 模块的类路径中。

Gradle 6.3 不支持32 位 Unix 系统和旧 FreeBSD 版本（早于 FreeBSD 10）的丰富控制台。 Microsoft Windows 32 位不受影响。

Gradle 将继续在 32 位系统上构建项目，但将不再显示丰富的控制台。

几乎每个 Gradle 项目都有由基本插件添加的默认配置和存档配置。这些配置不再在使用变体感知依赖管理和新发布插件的现代 Gradle 构建中使用。

虽然配置暂时保留在 Gradle 中以实现向后兼容性，但现在不推荐使用它们来声明依赖项或解析依赖项。

解决这些配置从来都不是预期的用例，唯一可能的原因是在早期的 Gradle 版本中，每个配置都是可解析的。要声明依赖项，请使用您使用的插件提供的配置，例如Java 库插件。

JVM 项目中的类路径现在显式请求该org.gradle.category=library属性。如果无法使用某个库，这会导致更清晰的错误消息。例如，当库不支持所需的 Java 版本时。实际效果是，现在所有平台依赖项都必须如此声明。之前，当platform()本地平台或使用 Gradle 模块元数据发布的平台省略关键字时，平台依赖项也会意外地发挥作用。

Gradle 6.2 和 Gradle 6.2.1 中存在回归，导致项目根gradle.properties文件中设置的 Gradle 属性泄漏到buildSrc构建以及根包含的任何构建中。

buildSrc如果构建或包含的构建突然发现来自项目根gradle.properties文件的属性存在意外或不兼容的值，这可能会导致您的构建开始失败。

该回归已在 Gradle 6.2.2 中修复。

在任务完成之前查询映射输出属性的值可能会导致奇怪的构建失败，因为这表明可能会错误地使用过时或不存在的输出。此行为已被弃用，并将发出弃用警告。这将成为 Gradle 7.0 中的错误。

下面的示例演示了在 Producer 执行之前解析 Producer 的输出文件的这个问题：

如果在完成之前查询 的值，consumer.threadPoolSize将产生弃用警告producer，因为尚未生成输出文件。

以下方法已停止使用，不应再使用。它们将在 Gradle 7.0 中被删除。

Gradle 2.x 中引入了一组用于 Java 和 Scala 开发的替代插件，作为基于“软件模型”的实验。这些插件现已弃用，最终将被删除。如果您仍在使用这些旧插件（ java-lang、scala-lang、jvm-component、jvm-resources、 ）之一，请查阅有关构建 Java 和 JVM 项目junit-test-suite的文档，以确定哪些稳定的 JVM 插件适合您的项目。

在 Gradle 6.0 中，该ProjectLayout服务通过服务注入可供工作人员操作使用。该服务允许可变状态泄漏到辅助操作中，并引入了一种在辅助操作中未声明依赖项的方法。

ProjectLayout已从可用服务中删除。正在使用的工作操作ProjectLayout应切换为注入projectDirectory或buildDirectory作为参数。

从 Gradle 6.2 开始，Gradle 在上传之前执行健全性检查，以确保您不会上传过时的文件（由另一个构建生成的文件）。这给使用该组件上传的 Spring Boot 应用程序带来了一个问题components.java：

这是由于jarSpring Boot 应用程序禁用了主任务，而组件希望它存在。由于该bootJar任务默认使用与主任务相同的文件，因此以前版本的 Gradle 会：jar

解决方法是告诉 Gradle 要上传什么。如果您想上传bootJar，那么您需要配置传出配置来执行此操作：

或者，您可能想要重新启用该jar任务，并添加bootJar不同的分类器。