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

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

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

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

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

自 Gradle 诞生以来，它提供了 compile 和 runtime 配置来声明依赖项。但是，这些配置不支持依赖项的细粒度范围。因此，在 Gradle 3.4 中引入了更好的替代方案

在 Gradle 7 中，compile 和 runtime 配置均已删除。因此，您必须迁移到上述 implementation 和 api 配置。如果您仍在为 Java 库使用 java 插件，则需要改用 java-library 插件。

你可以通过阅读Java 库插件文档，找到有关新配置的优势以及在何处使用它们以替代 compile 和 runtime 的更多详细信息。

ProjectBuilder API 用于在单元测试中检查 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 禁用了通过 GradleRunner 在 Windows 上执行的构建的文件系统监视。如果你想覆盖默认行为，可以通过将 --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。

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

采用配置块的 layout 方法已移除，并被 patternLayout 替换。

Gradle 构建由其在当前或父目录中找到的 settings.gradle(.kts) 文件定义。如果没有设置文件，则 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 文档。

org.gradle.jvm.toolchain 中支持 Java Toolchain 功能的 API 现标记为 @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 扩展已更改为优先使用 Gradle 的 Action<T> 类型而不是 Kotlin 函数类型。

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

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

自 Gradle 6.7 起，buildSrc 可以从根构建中看到任何包含的构建。这可能会导致从 buildSrc 中包含构建中的依赖项被替换。如果 buildSrc 需要包含的构建，这还可能会更改某些构建的执行顺序。

Gradle 的文件树应用一些默认排除模式以方便起见 - 实际上与 Ant 中的默认模式相同。有关更多信息，请参阅 用户手册。有时，Ant 的默认排除项会造成问题，例如当您想在存档文件中包含 .gitignore 时。

在执行阶段更改 Gradle 的默认排除项会导致正确性问题，并且已弃用。您只允许在设置脚本中更改 Gradle 的默认排除项，请参阅用户手册以获取示例。

Gradle 允许将 Configuration 的实例直接用作依赖项

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

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

有了此更改，围绕具有更丰富选择器的依赖项（例如平台依赖项）的现有替换将不再像以前那样工作。必须在目标选择器中定义变体感知部分。

如果您

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

AbstractTask 是在公共 API 中可见的内部类，作为公共类型 DefaultTask 的超类。AbstractTask 将在 Gradle 7.0 中移除，以下内容在 Gradle 6.5 中已弃用

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

在 Gradle 6.4 中，依赖项锁定 LockMode 的孵化 API 已更改。现在通过 Property<LockMode> 设置值，而不是直接设置器。这意味着必须为 Kotlin DSL 更新设置值符号

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

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

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

此版本在不同位置引入了几个新属性：mainClass、mainModule、modularity。由于这些是十分通用的名称，因此您有可能在构建脚本中将其中一个用作变量名称。然后，新属性可能会以不需要的方式覆盖您的某个变量，从而导致在访问属性而不是具有相同名称的局部变量时构建失败。您可以通过重命名构建脚本中的相应变量来修复它。

受影响的是 application {} 和 java {} 配置块内的配置代码，project.javaexec {} 内的 Java 执行设置，以及各种任务配置（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 项目都有 default 和 archives 配置，它们由 base 插件添加。在使用 变体感知依赖管理 和 新发布插件 的现代 Gradle 构建中不再使用这些配置。

虽然这些配置目前仍保留在 Gradle 中以保持向后兼容性，但现在不建议使用它们来声明依赖项或解析依赖项。

解析这些配置从来都不是预期用例，并且只有在早期 Gradle 版本中才有可能，因为在早期 Gradle 版本中每个配置都是可解析的。对于声明依赖项，请使用您所用插件提供的配置，例如 Java Library 插件。

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

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

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

此回归已在 Gradle 6.2.2 中修复。

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

以下示例演示了此问题，其中在 Producer 执行之前解析 Producer 的输出文件

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

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

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

在 Gradle 6.0 中，ProjectLayout 服务通过服务注入提供给工作器操作。此服务允许可变状态泄漏到工作器操作中，并引入了一种方法，使依赖项在工作器操作中保持未声明状态。

ProjectLayout 已从可用服务中移除。使用 ProjectLayout 的工作器操作应改为注入 projectDirectory 或 buildDirectory 作为参数。

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

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

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

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