将您的构建从 Gradle 4.x 升级到 5.0

本章提供了将旧版 Gradle 4.x 构建迁移到 Gradle 5.0 所需的信息。在大多数情况下，您需要应用从您要升级的版本之后的全部版本的更改。例如，如果您要从 Gradle 4.3 升级到 5.0，您还需要应用自 4.4、4.5 等直至 5.0 以来的更改。

如果您将 Gradle 用于 Android，您需要将 Android Gradle 插件和 Android Studio 都移至 3.3 或更高版本。

适用于所有用户

如果您尚未使用最新的 4.10.x 版本，请阅读以下部分，了解如何将您的项目升级到最新的 4.10.x 版本。我们建议您升级到最新的 4.10.x 版本，以便在迁移到 5.0 之前获得最有用的警告和弃用信息。为了在出现潜在问题时便于进行故障排除，请避免同时升级 Gradle 和迁移到 Kotlin DSL。
尝试运行 gradle help --scan 并查看生成的构建扫描的弃用视图。如果没有警告，则不会显示弃用选项卡。

这样您就可以看到适用于您的构建的任何弃用警告。如果您尝试直接升级到 Gradle 5.x，它将生成（可能不太明显的）错误。

或者，您可以运行 gradle help --warning-mode=all 以在控制台中查看弃用项，但它可能不会报告太多详细信息。
更新您的插件。

某些插件将与此新版本的 Gradle 冲突，例如因为它们使用已删除或更改的内部 API。当插件尝试使用 API 的弃用部分时，上一步将通过发出弃用警告来帮助您识别潜在问题。

特别是，您将需要使用至少 2.x 版本的 Shadow 插件。
运行 gradle wrapper --gradle-version 5.0 以将项目更新到 5.0
如果您尚未迁移，请迁移到 Java 8 或更高版本。Gradle 4.x 需要 Java 7，而 Gradle 5 需要 Java 8 才能运行。
阅读从 4.10 升级部分并进行任何必要的更改。
尝试运行项目并使用故障排除指南调试任何错误。

此外，Gradle 还添加了一些重要的新增功能和改进功能，您应该考虑在构建中使用这些功能

Maven 发布和 Ivy 发布插件现在支持使用签名插件进行数字签名。
在您的构建中使用本机 BOM 导入。
工作器 API 用于启用工作单元并行运行。
用于延迟创建和配置任务的新 API，可以显著改善您的构建的配置时间。

其他需要注意的可能破坏您的构建的显着更改包括

使用 POM 时编译和运行时依赖项的分离
这意味着您应该配置现有的 wrapper 和 init 任务而不是定义您自己的任务的更改。
尊重 Maven POM 排除中的隐式通配符，这可能导致排除以前未排除的依赖项。
向项目中添加 Java 注解处理器的更改。
命令行客户端、Gradle 守护程序以及包括编译器和测试执行器在内的所有工作器的默认内存设置已大大减少。
几个代码质量插件的默认版本已更新。
Gradle 使用的几个库版本已升级。

从 4.10 及更早版本升级

如果您尚未使用 4.10 版本，请跳到适用于您当前 Gradle 版本的部分，并一直向上，直到您到达此处。然后，在从 Gradle 4.10 迁移到 5.0 时应用这些更改。

其他更改

enableFeaturePreview('IMPROVED_POM_SUPPORT') 和 enableFeaturePreview('STABLE_PUBLISHING') 标志不再需要。这些功能现在默认启用。
Gradle 现为 Java 9 及更高版本捆绑 JAXB。如果已设置，可以从 org.gradle.jvmargs 中移除 --add-modules java.xml.bind 选项。

潜在中断性变更

本节中的变更可能会中断您的构建，但绝大多数变更已弃用了一段时间，并且很少有构建会受到大量变更的影响。我们强烈建议先升级到 Gradle 4.10，以获取有关弃用内容如何影响您的构建的报告。

以下中断性变更并非源自弃用，而是行为变更的结果

使用 POM 时编译和运行时依赖项的分离
publishing {} 块的评估不再推迟到需要时才进行，而是像任何其他块一样进行。如果您需要推迟评估，请使用 afterEvaluate {}。
Javadoc 和 Groovydoc 任务现在在执行前删除文档的目标目录。此项添加是为了移除上次任务执行中过时的输出文件。
Java 库分发插件现在基于 Java 库插件，而不是 Java 插件。

虽然它应用了 Java 插件，但行为略有不同（例如，它添加了 api 配置）。因此，请务必在升级后检查您的构建是否按预期进行。
CheckstyleReport 和 FindBugsReport 上的 html 属性现在返回一个 CustomizableHtmlReport 实例，该实例更容易从 Java 和 Kotlin 等静态类型语言进行配置。
配置规避 API 已更新，以防止创建和配置从未使用的任务。
命令行客户端、Gradle 守护程序以及包括编译器和测试执行器在内的所有工作器的默认内存设置已大大减少。
几个代码质量插件的默认版本已更新。
Gradle 使用的几个库版本已升级。

以下中断性变更将显示为 Gradle 4.10 的弃用警告

常规

任务定义不再使用 <<。换句话说，您不能使用语法 task myTask << { … }。

请改用 Task.doLast() 方法，如下所示
```
task myTask {
    doLast {
        ...
    }
}
```
您不能再在诸如项目和任务名称的域对象名称中使用以下任何字符：<space> / \ : < > " ? * | 。您也不应将 . 用作前导或尾随字符。

运行 Gradle 和构建环境

如前所述，Gradle 不再可以在 Java 7 上运行。但是，您仍然可以使用分叉编译和测试为 Java 6 及更高版本构建和测试软件。
-Dtest.single 命令行选项已删除 — 请改用测试筛选。
-Dtest.debug 命令行选项已删除 — 请改用 --debug-jvm 选项。
-u/--no-search-upward 命令行选项已删除 — 请确保您的所有构建都具有 settings.gradle 文件。
--recompile-scripts 命令行选项已删除。
除非嵌套构建具有 settings.gradle 文件，否则您不能再将 Gradle 构建嵌套在另一个 Gradle 构建的子目录中。
DirectoryBuildCache.setTargetSizeInMB(long) 方法已删除 — 请改用 DirectoryBuildCache.removeUnusedEntriesAfterDays。
org.gradle.readLoggingConfigFile 系统属性不再执行任何操作 — 请更新受影响的测试以使用您的 java.util.logging 设置。

使用文件

您不能再使用 as 关键字或 asType() 方法将 FileCollection 对象强制转换为其他类型。
您不能再将 null 传递为 CopySpec.from(Object, Action) 的配置操作。
为了更好地兼容 Kotlin DSL，CopySpec.duplicatesStrategy 不再可为 null。属性设置器不再接受 null 作为将属性重置回其默认值的方法。请改用 DuplicatesStrategy.INHERIT。
FileCollection.stopExecutionIfEmpty() 方法已删除 — 请改用 FileCollection 任务属性上的 @SkipWhenEmpty 注释。
FileCollection.add() 方法已删除 — 请使用 Project.files() 和 Project.fileTree() 创建可配置的文件集合/文件树，并通过 ConfigurableFileCollection.from() 将其添加到其中。
SimpleFileCollection 已被移除 — 请改用 Project.files(Object…)。
不要让您自己的类扩展 AbstractFileCollection — 请改用 Project.files() 方法。此问题可能表现为缺少 getBuildDependencies() 方法。

Java 构建

CompileOptions.bootClasspath 属性已移除 — 请改用 CompileOptions.bootstrapClasspath。
您不再可以使用 -source-path 作为通用编译器参数 — 请改用 CompileOptions.sourcepath。
您不再可以使用 -processorpath 作为通用编译器参数 — 请改用 CompileOptions.annotationProcessorPath。
Gradle 将不再自动应用位于编译类路径上的注释处理器 — 请改用 CompileOptions.annotationProcessorPath。
testClassesDir 属性已从 Test 任务中移除 — 请改用 testClassesDirs。
classesDir 属性已从 JDepend 任务和 SourceSetOutput 中移除。请改用 JDepend.classesDirs 和 SourceSetOutput.classesDirs 属性。
JavaLibrary(PublishArtifact, DependencySet) 构造函数已移除 — 这是 Shadow 插件使用的，因此请确保升级到该插件的至少 2.x 版本。
JavaBasePlugin.configureForSourceSet() 方法已移除。
您不再可以创建 JavaPluginConvention、ApplicationPluginConvention、WarPluginConvention、EarPluginConvention、BasePluginConvention 和 ProjectReportsPluginConvention 的自己的实例。
Maven 插件用于发布高度过时的 Maven 2 元数据格式。这已更改，现在它将发布 Maven 3 元数据，就像 Maven Publish 插件一样。

随着 Maven 2 支持的移除，配置唯一快照行为的方法也已移除。Maven 3 仅支持唯一快照，因此我们决定移除它们。

任务和属性

与惰性属性相关的以下旧类和方法已被移除——使用ObjectFactory.property()创建Property实例
- PropertyState
- DirectoryVar
- RegularFileVar
- ProjectLayout.newDirectoryVar()
- ProjectLayout.newFileVar()
- Project.property(Class)
- Script.property(Class)
- ProviderFactory.property(Class)
使用任务配置规避API配置和注册的任务对可以从配置操作调用的其他方法有更多限制。
内部@Option和@OptionValues注释——包org.gradle.api.internal.tasks.options——已被移除。请改用公共@Option和@OptionValues注释。
Task.deleteAllActions()方法已被移除，没有替换。
Task.dependsOnTaskDidWork()方法已被移除——改用声明的输入和输出。
TaskInternal的以下属性和方法已被移除——改用任务依赖项、任务规则、可重用实用方法或Worker API来代替直接执行任务。
- execute()
- executer
- getValidators()
- addValidator()
TaskInputs.file(Object)方法不再可以调用，其参数解析为除单个常规文件之外的任何内容。
TaskInputs.dir(Object)方法不再可以调用，其参数解析为除单个目录之外的任何内容。
您不再可以通过TaskInputs和TaskOutputs注册无效的输入和输出。
TaskDestroyables.file()和TaskDestroyables.files()方法已被移除——改用TaskDestroyables.register()。
SimpleWorkResult已被移除——改用WorkResult.didWork。
覆盖4.8 中已弃用的内置任务现在会产生错误。

尝试替换内置任务会产生类似于以下内容的错误
```
> Cannot add task 'wrapper' as a task with that name already exists.
```

Scala 和 Play

Play 2.2 不再受支持——请升级您正在使用的 Play 版本。
ScalaDocOptions.styleSheet属性已被移除——Scala 2.11.8 及更高版本中的 Scaladoc Ant 任务不再支持此属性。

Kotlin DSL

工件配置访问器现在具有类型 NamedDomainObjectProvider<Configuration>，而不是 Configuration
PluginAware.apply<T>(to) 已重命名为 PluginAware.applyTo<T>(target)。

这两个更改都可能导致脚本编译错误。有关详细信息以及如何修复因上述更改而损坏的构建，请参阅 Gradle Kotlin DSL 发行说明。

其他

ConfigurableReport.setDestination(Object) 方法已删除 — 请改用 ConfigurableReport.setDestination(File)。
Signature.setFile(File) 方法已删除 — Gradle 不支持更改生成签名的输出文件。
只读 Signature.toSignArtifact 属性已删除 — 它永远不应成为公共 API 的一部分。
@DeferredConfigurable 注释已删除。
isDeferredConfigurable() 方法已从 ExtensionSchema 中删除。
IdeaPlugin.performPostEvaluationActions() 和 EclipsePlugin.performPostEvaluationActions() 已删除。
The `BroadcastingCollectionEventRegister.getAddAction() 方法已删除，没有替代方法。
内部 org.gradle.util 包不再默认导入。

理想情况下，你不应该使用此包中的类，但作为快速修复，你可以为构建脚本中的那些类添加显式导入。
gradlePluginPortal() 存储库默认情况下不再查找没有 POM 的 JAR。
Tooling API 不再能够使用低于 Gradle 2.6 的 Gradle 版本连接到构建。通过 TestKit 运行的构建也适用此规则。
Gradle 5.0 要求最低 Tooling API 客户端版本为 3.0。较旧的客户端库不再能够使用 Gradle 5.0 运行构建。
IdeaModule Tooling API 模型元素包含检索资源和测试资源的方法，因此这些元素已从 IdeaModule.getSourceDirs() 和 IdeaModule.getTestSourceDirs() 的结果中删除。
在以前的 Gradle 版本中，子类可以访问 SourceTask 中的 source 字段。现在不再是这样，因为 source 字段现在声明为 private。
在 Worker API 中，不再能够设置 worker 的工作目录。
与依赖项和版本约束相关的行为更改可能会影响少数用户。
DefaultTask 上的属性工厂方法已进行了几项更改，这可能会影响自定义任务的创建。

从 4.9 及更早版本升级

如果您尚未使用 4.9 版本，请跳到适用于您当前 Gradle 版本的部分，然后一直向上，直到到达此处。然后，在升级到 Gradle 4.10 时应用这些更改。

已弃用的类、方法和属性

请按照 API 链接了解如何处理这些弃用（如果此处未提供其他信息）

TaskContainer.add() 和 TaskContainer.addAll() — 改用 TaskContainer.create() 或 TaskContainer.register()

潜在的不兼容更改

Kotlin DSL 中有几个潜在的不兼容更改 — 请参阅该项目的发布说明中的不兼容更改部分。
您不再可以使用任何 Project.beforeEvaluate() 或 Project.afterEvaluate() 方法进行延迟任务配置，例如在 TaskContainer.register() 块中。
发布到 AWS S3 需要新的权限.
由 Java Gradle 插件开发插件使用的 PluginUnderTestMetadata 和 GeneratePluginDescriptors 这两个类已更新为使用 Provider API。

使用 Property.set() 方法修改其值，而不是使用标准属性赋值语法，除非您在 Groovy 构建脚本中这样做。在这种情况下，标准属性赋值仍然有效。

从 4.8 及更早版本升级

考虑尝试用于任务创建和配置的延迟 API

潜在的不兼容更改

您不再可以使用 GPath 语法与 tasks.withType() 一起使用。

改用 Groovy 的展开运算符。例如，你可以将 tasks.withType(JavaCompile).name 替换为 tasks.withType(JavaCompile)*.name。

从 4.7 及更早版本升级

切换到 Maven Publish 和 Ivy Publish 插件
对发布插件使用延迟配置
配置现有的 wrapper 和 init 任务，而不是定义你自己的任务
如果你目前正在为此使用插件或自定义解决方案，请考虑迁移到内置的依赖锁定机制

潜在的破坏性更改

如果找不到指定的初始化脚本，构建现在将失败。
TaskContainer.remove() 现在实际上会移除给定的任务 — 一些插件可能意外地依赖于旧的行为。
Gradle 现在支持 Maven POM 排除中的隐式通配符.
Kotlin DSL 现在遵循 JSR-305 包注释。

这将导致一些根据 JSR-305 注释的类型被视为可空，而之前它们被视为不可空。这可能会导致构建脚本中出现编译错误。有关详细信息，请参阅相关的 Kotlin DSL 发行说明。
除非控制台同时附加到标准输出和标准错误，否则错误消息现在将定向到标准错误，而不是标准输出。这可能会影响抓取构建的纯控制台输出的工具。如果你从 Gradle 的早期版本升级，请忽略此更改。

弃用

在此版本之前，构建允许替换内置任务。此功能已被弃用。

不应替换的内置任务的完整列表：wrapper、init、help、tasks、projects、buildEnvironment、components、dependencies、dependencyInsight、dependentComponents、model、properties。

从 4.6 及更早版本升级

潜在的破坏性更改

根据惯例，Gradle 现在将在根项目的 config/checkstyle 目录中查找 Checkstyle 配置文件。

子项目中的 Checkstyle 配置文件（旧的约定位置）将被忽略，除非您通过 checkstyle.configDir 或 checkstyle.config 明确配置其路径。
Gradle 的纯控制台输出的结构已更改，这可能会破坏抓取该输出的工具。
与编译、链接和安装相关的许多本机任务的 API 已以破坏性方式更改。
[Kotlin DSL] 用于访问 Gradle 构建属性的委托属性（例如在 gradle.properties 中定义的属性）现在必须显式输入。
[Kotlin DSL] 现在，在嵌套作用域内声明 plugins {} 块会抛出异常。
[Kotlin DSL] 现在只允许一个 pluginManagement {} 块。
org.gradle.api.artifacts.cache.* 接口提供的缓存控制 DSL 不再可用。
getEnabledDirectoryReportDestinations()、getEnabledFileReportDestinations() 和 getEnabledReportNames() 已全部从 org.gradle.api.reporting.ReportContainer 中移除。
StartParameter.projectProperties 和 StartParameter.systemPropertiesArgs 现在返回不可变映射。

从 4.5 及更早版本升级

弃用

您不应将注释处理器放在编译类路径上，也不应使用 -processorpath 编译器参数声明它们。

应该将它们添加到 annotationProcessor 配置中。如果您不希望进行任何处理，但您的编译类路径意外包含了一个处理器（例如作为您依赖的库的一部分），请使用 -proc:none 编译器参数来忽略它。
使用 CommandLineArgumentProvider 来代替 CompilerArgumentProvider。

潜在的破坏性更改

Java 插件现在为每个源集添加一个 sourceSetAnnotationProcessor 配置，如果其中任何一个与您现有的配置匹配，则可能会中断。我们建议您删除冲突的配置声明。
StartParameter.taskOutputCacheEnabled 属性已被 StartParameter.setBuildCacheEnabled(boolean) 替换。
Visual Studio 集成现在只为构建中的所有组件配置一个解决方案。
Gradle 已将 HttpClient 4.4.1 替换为版本 4.5.5。
Gradle 现在捆绑 kotlin-stdlib-jdk8 工件，而不是 kotlin-stdlib-jre8。这可能会影响您的构建。有关更多详细信息，请参阅 Kotlin 文档。

从 4.4 及更早版本升级

确保您有一个 settings.gradle 文件：它可以避免性能损失，并允许您设置根项目的名称。
Gradle 现在忽略包含的构建（复合构建）的构建缓存配置，而是为所有构建使用根构建的配置。

潜在的重大更改

已删除两个重载的 ValidateTaskProperties.setOutputFile() 方法。当从构建脚本访问任务时，它们会被自动生成的设置器替换，但从构建脚本之外的插件和其他代码中不会发生这种情况。
Maven 发布插件现在生成更完整的 maven-metadata.xml 文件，包括维护 <snapshotVersion> 元素的列表。某些较旧版本的 Maven 可能无法使用此元数据。
HttpBuildCache 不再遵循重定向.
已删除 Depend 任务类型。
Project.file(Object) 不再对不区分大小写的文件系统上的文件路径进行大小写规范化。它现在在这种情况下忽略大小写，并且不触及文件系统。
ListProperty 不再扩展 Property。

从 4.3 及更早版本升级

潜在的重大更改

AbstractTestTask 现在由非 JVM 测试任务以及 Test 扩展。因此，插件应注意配置所有类型为 AbstractTestTask 的任务。
EclipseClasspath.defaultOutputDir 的默认输出位置已从 $projectDir/bin 更改为 $projectDir/bin/default。
已删除弃用的 InstallExecutable.setDestinationDir(Provider) — 请改用 InstallExecutable.installDirectory。
已删除弃用的 InstallExecutable.setExecutable(Provider) — 请改用 InstallExecutable.executableFile。
Gradle 不再将路径中找到的 Visual Studio 版本优先于其他位置。现在这是最后的手段。

您可以通过 VisualCpp.setInstallDir(Object) 指定所需 Visual Studio 版本的安装目录，绕过工具链发现。
pluginManagement.repositories 现在是 RepositoryHandler 类型，而不是已删除的 PluginRepositoriesSpec。
依赖项解析期间的 5xx HTTP 错误现在将在构建中触发异常。
已将嵌入式 Apache Ant 从 1.9.6 升级到 1.9.9。
Gradle 使用的多个第三方库已升级以修复安全问题。

从 4.2 及更早版本升级

现在可以在子项目和 buildSrc 目录中的插件中使用 plugins {} 块。

其他弃用

您不再应该通过 Tooling API 运行低于 2.6 的 Gradle 版本。
您不再应该通过低于 3.0 的 Tooling API 运行任何 Gradle 版本。
您不再应该链接 TaskInputs.property(String,Object) 和 TaskInputs.properties(Map) 方法。

潜在的重大更改

DefaultTask.newOutputDirectory() 现在返回 DirectoryProperty 而不是 DirectoryVar。
DefaultTask.newOutputFile() 现在返回 RegularFileProperty 而不是 RegularFileVar。
DefaultTask.newInputFile() 现在返回 RegularFileProperty 而不是 RegularFileVar。
ProjectLayout.buildDirectory 现在返回 DirectoryProperty 而不是 DirectoryVar。
AbstractNativeCompileTask.compilerArgs 现在是 ListProperty<String> 类型，而不是 List<String>。
AbstractNativeCompileTask.objectFileDir 现在是 DirectoryProperty 类型，而不是 File。
AbstractLinkTask.linkerArgs 现在是 ListProperty<String> 类型，而不是 List<String>。
TaskDestroyables.getFiles() 不再是公共 API 的一部分。
依赖项的重叠版本范围现在会导致 Gradle 选择满足所有声明范围的版本。

例如，如果发现对 some-module 的依赖项版本范围为 [3,6]，并且还通过传递依赖项范围为 [4,8]，Gradle 现在选择版本 6 而不是 8。之前的行为是选择 8。
标记为 @OutputFiles 或 @OutputDirectories 的 Iterable 属性中元素的顺序现在很重要。如果顺序发生变化，则不再认为该属性是最新的。

最好使用带有 @OutputFile/@OutputDirectory 注解的单独属性，或使用带有 @OutputFiles/@OutputDirectories 的 Map 属性。
当存在另一个可以检查的存储库时，Gradle 将不再忽略来自存储库的依赖项解析错误。依赖项解析将失败。这会导致解析结果更确定。

从 4.1 及更早版本升级

潜在的重大更改

TaskFilePropertyBuilder 和 TaskOutputFilePropertyBuilder 上的 withPathSensitivity() 方法已删除。
已将捆绑的 bndlib 从 3.2.0 升级到 3.4.0。
FindBugs 插件不再呈现其分析的进度信息。如果您以任何方式依赖该输出，可以使用 FindBugs.showProgress 启用它。

从 4.0 升级

考虑使用新的 Worker API，以使构建中的工作单元能够并行运行。

已弃用的类、方法和属性

请按照 API 链接了解如何处理这些弃用（如果此处未提供其他信息）

可空

潜在破坏性变更

对 Java 项目有项目依赖项的非 Java 项目现在默认使用 runtimeElements 配置，而不是 default 配置。

要覆盖此行为，您可以在项目依赖项中明确声明要使用的配置。例如：project(path: ':myJavaProject', configuration: 'default')。
默认 Zinc 编译器从 0.3.13 升级到 0.3.15。
[Kotlin DSL] 基本包从 org.gradle.script.lang.kotlin 重命名为 org.gradle.kotlin.dsl。

详细变更

[5.0] 默认内存设置已更改

命令行客户端现在以 64MB 堆内存启动，而不是 1GB。这可能会影响使用 --no-daemon 模式在客户端 VM 中直接运行的构建。我们不建议使用 --no-daemon，但如果您必须使用它，则可以使用 GRADLE_OPTS 环境变量增加可用内存。

Gradle 守护进程现在以 512MB 堆内存启动，而不是 1GB。大型项目可能需要使用 org.gradle.jvmargs 属性增加此设置。

所有工作进程（包括编译器和测试执行器）现在都以 512MB 堆内存启动。之前的默认值为物理内存的 1/4。大型项目可能需要在相关任务（例如 JavaCompile 或 Test）上增加此设置。

[5.0] 代码质量插件的新默认版本

以下代码质量插件的默认工具版本已更新

Checkstyle 插件现在默认使用 8.12，而不是 6.19。
CodeNarc 插件现在默认使用 1.2.1，而不是 1.1。
JaCoCo 插件现在默认使用 0.8.2，而不是 0.8.1。
默认情况下，PMD 插件现在使用 6.8.0，而不是 5.6.1。

此外，默认规则集已从现已弃用的 java-basic 更改为 category/java/errorprone.xml。

不过，我们建议明确配置规则集。

[5.0] 库升级

Gradle 使用的多个库已升级

Groovy 已从 2.4.15 升级到 2.5.4。
Ant 已从 1.9.11 升级到 1.9.13。
用于访问 S3 支持的 Maven/Ivy 存储库的 AWS SDK 已从 1.11.267 升级到 1.11.407。
OSGi 插件使用的 BND 库已从 3.4.0 升级到 4.0.0。
用于访问 Google Cloud Storage 支持的 Maven/Ivy 存储库的 Google Cloud Storage JSON API 客户端库已从 v1-rev116-1.23.0 升级到 v1-rev136-1.25.0。
Ivy 已从 2.2.0 升级到 2.3.0。
Test 任务使用的 JUnit Platform 库已从 1.0.3 升级到 1.3.1。
用于访问 Maven 存储库的 Maven Wagon 库已从 2.4 升级到 3.0.0。
SLF4J 已从 1.7.16 升级到 1.7.25。

[5.0] 改进对依赖项和版本约束的支持

通过 Gradle 4.x 发布流，依赖项解析引擎添加了新的 @Incubating 功能。其中包括复杂的版本约束（prefer、strictly、reject）、依赖项约束和 platform 依赖项。

如果您一直在使用 IMPROVED_POM_SUPPORT 功能预览，使用约束或 prefer、reject 和其他特定版本指示，那么请务必仔细查看您的依赖项解析结果。

[5.0] BOM 导入

Gradle 现在支持导入物料清单 (BOM) 文件，这些文件实际上是使用 <dependencyManagement> 部分控制直接和传递依赖项版本的 POM 文件。您需要做的就是将 POM 声明为 platform 依赖项。

以下示例从声明的 Spring Boot BOM 中选取 gson 和 dom4j 依赖项的版本

dependencies {
    // import a BOM
    implementation platform('org.springframework.boot:spring-boot-dependencies:1.5.8.RELEASE')

    // define dependencies without versions
    implementation 'com.google.code.gson:gson'
    implementation 'dom4j:dom4j'
}

[5.0] 使用 POM 时编译和运行时依赖项分离

自 Gradle 1.0 以来，运行时范围的依赖项已包含在 Java 编译类路径中，这有一些缺点

编译类路径比需要的大得多，从而减慢了编译速度。
编译类路径包含不影响编译的运行时范围的文件，导致在这些文件更改时进行不必要的重新编译。

使用此新行为，Java 和 Java 库插件都遵守编译和运行时范围分离。这意味着编译类路径仅包含编译范围的依赖项，而运行时类路径也会添加运行时范围的依赖项。如果您使用 Gradle 开发和发布 Java 库，则此功能特别有用，其中 api 和 implementation 依赖项之间的分离反映在已发布的范围内。

[5.0] 对 `DefaultTask` 上的属性工厂方法进行更改

`DefaultTask` 上的属性工厂方法现在是最终的

属性工厂方法（如 newInputFile()）旨在从扩展 DefaultTask 的类型的构造函数中调用。这些方法现在是最终的，以避免子类覆盖这些方法并使用未初始化的状态。

输入和输出不会自动注册

这些方法返回的属性实例不再自动注册为任务的输入或输出。属性实例需要以通常的方式声明为输入或输出，例如附加注释（如 @OutputFile）或使用运行时 API 注册属性。

例如，您以前可以使用以下语法并将两个 outputFile 实例注册为已声明的输出

build.gradle

class MyTask extends DefaultTask {
    // note: no annotation here
    final RegularFileProperty outputFile = newOutputFile()
}

task myOtherTask {
    def outputFile = newOutputFile()
    doLast { ... }
}

build.gradle.kts

open class MyTask : DefaultTask() {
    // note: no annotation here
    val outputFile: RegularFileProperty = newOutputFile()
}

task("myOtherTask") {
    val outputFile = newOutputFile()
    doLast { ... }
}

现在，您必须显式注册 outputFile，如下所示

build.gradle

class MyTask extends DefaultTask {
    @OutputFile // property needs an annotation
    final RegularFileProperty outputFile = project.objects.fileProperty()
}

task myOtherTask {
    def outputFile = project.objects.fileProperty()
    outputs.file(outputFile) // or to be registered using the runtime API
    doLast { ... }
}

build.gradle.kts

open class MyTask : DefaultTask() {
    @OutputFile // property needs an annotation
    val outputFile: RegularFileProperty = project.objects.fileProperty()
}

task("myOtherTask") {
    val outputFile = project.objects.fileProperty()
    outputs.file(outputFile) // or to be registered using the runtime API
    doLast { ... }
}

[5.0] Gradle 现在捆绑了适用于 Java 9 及更高版本的 JAXB

为了使用 S3 支持的工件存储库，以前必须在 Java 9 及更高版本上运行时将 --add-modules java.xml.bind 添加到 org.gradle.jvmargs。

由于 Java 11 不再包含 java.xml.bind 模块，因此 Gradle 现在捆绑了 JAXB 2.3.1（com.sun.xml.bind:jaxb-impl）并在 Java 9 及更高版本上使用它。

如果已设置，请从 org.gradle.jvmargs 中删除 --add-modules java.xml.bind 选项。

[5.0] `gradlePluginPortal()` 存储库不再默认查找没有 POM 的 JAR

有了此新行为，如果在 gradlePluginPortal() 存储库中找到的插件或插件的传递依赖项没有 Maven POM，则它将无法解析。

应该修复发布到 Maven 存储库且没有 POM 的工件。如果您遇到此类工件，请要求插件或库作者发布具有适当元数据的版本。

如果您遇到错误的插件，可以通过重新启用 JAR 作为 gradlePluginPortal() 存储库的元数据源来解决此问题

settings.gradle

pluginManagement {
    repositories {
        gradlePluginPortal().tap {
            metadataSources {
                mavenPom()
                artifact()
            }
        }
    }
}

settings.gradle.kts

pluginManagement {
    repositories {
        gradlePluginPortal().apply {
            (this as MavenArtifactRepository).metadataSources {
                mavenPom()
                artifact()
            }
        }
    }
}

Java 库分发插件利用 Java 库插件

Java 库分发插件现在基于 Java 库插件，而不是 Java 插件。

此外，插件创建的默认分发将包含 runtimeClasspath 配置的所有工件，而不是已弃用的 runtime 配置。

配置规避 API 禁止常见配置错误

Gradle 4.9 中引入的配置规避 API允许您避免创建和配置从未使用过的任务。

使用现有 API，此示例添加了两个任务（foo 和 bar）

build.gradle

tasks.create("foo") {
    tasks.create("bar")
}

build.gradle.kts

tasks.create("foo") {
    tasks.create("bar")
}

在转换为使用新 API 时，会发生一些令人惊讶的事情：bar 不存在。新 API 仅在必要时才执行配置操作，因此任务 bar 的 register() 仅在配置 foo 时才执行。

build.gradle

tasks.register("foo") {
    tasks.register("bar") // WRONG
}

build.gradle.kts

tasks.register("foo") {
    tasks.register("bar") // WRONG
}

为了避免这种情况，Gradle 现在检测到这一点，并在使用新 API 时阻止对基础容器（通过 create() 或 register()）进行修改。

[5.0] 工作器 API：不再可以设置工作器的当前目录

由于 JDK 11 不再支持更改正在运行的进程的当前目录，因此现在禁止通过其 fork 选项设置工作器的当前目录。

所有工作器现在使用相同的当前目录以启用重用。

请改用将文件和目录作为参数传递。

[4.10] 发布到 AWS S3 需要新的权限

S3 存储库传输协议允许 Gradle 将工件发布到 AWS S3 存储桶。从本版本开始，上传到 S3 存储桶的每个工件都将配备 bucket-owner-full-control 预设 ACL。确保用于发布工件的 AWS 帐户具有 s3:PutObjectAcl 和 s3:PutObjectVersionAcl 权限，否则上传将失败。

{
    "Version":"2012-10-17",
    "Statement":[
        // ...
        {
            "Effect":"Allow",
            "Action":[
                "s3:PutObject", // necessary for uploading objects
                "s3:PutObjectAcl", // required starting with this release
                "s3:PutObjectVersionAcl" // if S3 bucket versioning is enabled
            ],
            "Resource":"arn:aws:s3:::myCompanyBucket/*"
        }
    ]
}

有关更多信息，请参见 AWS S3 跨帐户访问。

[4.9] 考虑尝试使用延迟 API 进行任务创建和配置

Gradle 4.9 引入了一种新的方式来创建和配置以延迟方式工作的任务。当您对配置成本高昂的任务或拥有许多任务时使用此方法时，当这些任务不运行时，您的构建配置时间可能会大幅缩短。

您可以在任务配置规避章节中了解有关延迟创建任务的更多信息。您还可以在此博客文章中阅读有关此新功能的背景信息。

[4.8] 切换到 Maven 发布和 Ivy 发布插件

现在发布插件已稳定，我们建议您从标准 Java 项目（即基于 Java 插件的项目）的旧发布机制迁移。其中包括使用以下任一插件的项目：Java 库插件、应用程序插件或 War 插件。

要使用新方法，只需用 publishing {} 块替换任何 upload<Conf> 配置。有关更多信息，请参见发布概述章节。

[4.8] 对发布插件使用延迟配置

在 Gradle 4.8 之前，publishing {} 块被隐式视为在项目评估后执行其内部的所有逻辑。这令人困惑，因为这是唯一以这种方式工作的块。作为 Gradle 4.8 中稳定工作的一部分，我们正在弃用此行为，并要求所有用户迁移其构建。

可以通过将以下内容添加到您的设置文件中来启用新的稳定行为

settings.gradle

enableFeaturePreview('STABLE_PUBLISHING')

settings.gradle.kts

enableFeaturePreview("STABLE_PUBLISHING")

我们建议使用本地存储库进行测试运行，以查看所有工件是否仍具有预期的坐标。在大多数情况下，一切应该像以前一样工作，并且您已经完成。但是，您的发布块可能依赖于隐式延迟配置，特别是如果它依赖于在构建的配置阶段可能更改的值。

例如，在新行为下，以下逻辑假定 jar.archiveBaseName 在设置 artifactId 后不会更改

build.gradle

subprojects {
    publishing {
        publications {
            mavenJava {
                from components.java
                artifactId = jar.archiveBaseName
            }
        }
    }
}

build.gradle.kts

subprojects {
    publishing {
        publications {
            named<MavenPublication>("mavenJava") {
                from(components["java"])
                artifactId = tasks.jar.get().archiveBaseName.get()
            }
        }
    }
}

如果该假设不正确或将来可能不正确，则必须在 afterEvaluate {} 块中设置 artifactId，如下所示

build.gradle

subprojects {
    publishing {
        publications {
            mavenJava {
                from components.java
                afterEvaluate {
                    artifactId = jar.archiveBaseName
                }
            }
        }
    }
}

build.gradle.kts

subprojects {
    publishing {
        publications {
            named<MavenPublication>("mavenJava") {
                from(components["java"])
                afterEvaluate {
                    artifactId = tasks.jar.get().archiveBbaseName.get()
                }
            }
        }
    }
}

[4.8] 配置现有的 `wrapper` 和 `init` 任务

您不再应该定义自己的 wrapper 和 init 任务。相反，配置现有任务，例如将此

build.gradle

task wrapper(type: Wrapper) {
    ...
}

build.gradle.kts

task<Wrapper>("wrapper") {
    ...
}

转换为此

build.gradle

wrapper {
    ...
}

build.gradle.kts

tasks.wrapper {
    ...
}

[4.8] Gradle 现在支持 Maven POM 排除中的隐式通配符

如果 Maven POM 中的排除项缺少 groupId 或 artifactId，Gradle 过去会忽略该排除项。现在，缺少的元素被视为隐式通配符 — 例如 <groupId>*</groupId> — 这意味着您的一些依赖项现在可能会被排除在外，而以前不会被排除在外。

您需要明确声明您需要的任何缺少的依赖项。

[4.7] Gradle 纯控制台输出的结构更改

纯控制台模式现在以与富控制台一致的方式格式化输出，这意味着输出格式已更改。例如

由给定任务产生的输出现在被分组在一起，即使其他任务与它并行执行也是如此。
任务执行标题以“> 任务”前缀打印。
在构建执行期间产生的所有输出都将写入标准输出文件句柄。这包括写入 System.err 的消息，除非您将标准错误重定向到文件或任何其他非控制台目的地。

这可能会破坏从纯控制台输出中抓取详细信息的工具。

[4.6] 与编译、链接和安装相关的本机任务 API 的更改

许多与编译、链接和安装本机库和应用程序相关的任务已转换为 Provider API，以便它们支持延迟配置。此转换对任务的 API 带来了一些重大更改，以便它们与 Provider API 的约定相匹配。

已更改以下任务

AbstractLinkTask 及其子类

getDestinationDir() 已被 getDestinationDirectory() 取代。
getBinaryFile()、getOutputFile() 已被 getLinkedFile() 取代。
setOutputFile(File) 已被移除。请改用 Property.set()。
setOutputFile(Provider) 已被移除。请改用 Property.set()。
getTargetPlatform() 已更改为返回 Property。
setTargetPlatform(NativePlatform) 已被移除。请改用 Property.set()。
getToolChain() 已更改为返回 Property。
setToolChain(NativeToolChain) 已被移除。请改用 Property.set()。

CreateStaticLibrary

getOutputFile() 已更改为返回 Property。
setOutputFile(File) 已被移除。请改用 Property.set()。
setOutputFile(Provider) 已被移除。请改用 Property.set()。
getTargetPlatform() 已更改为返回 Property。
setTargetPlatform(NativePlatform) 已被移除。请改用 Property.set()。
getToolChain() 已更改为返回 Property。
setToolChain(NativeToolChain) 已被移除。请改用 Property.set()。
getStaticLibArgs() 已更改为返回 ListProperty。
setStaticLibArgs(List) 已被移除。请改用 ListProperty.set()。

InstallExecutable

getSourceFile() 已被 getExecutableFile() 取代。
getPlatform() 已被 getTargetPlatform() 取代。
setTargetPlatform(NativePlatform) 已被移除。请改用 Property.set()。
getToolChain() 已更改为返回 Property。
setToolChain(NativeToolChain) 已被移除。请改用 Property.set()。

以下内容也经历了类似的更改

[4.6] Visual Studio 集成仅支持生成所有组件的单个解决方案文件

VisualStudioExtension 不再具有 solutions 属性。相反，您通过根项目中的 VisualStudioRootExtension 配置单个解决方案，如下所示

build.gradle

model {
    visualStudio {
        solution {
            solutionFile.location = "vs/${name}.sln"
        }
    }
}

此外，不再有用于为每个组件生成解决方案文件的单独任务，而是一个生成包含生成中所有组件的解决方案文件的 visualStudio 任务。

[4.5] `HttpBuildCache` 不再关注重定向

当通过 HttpBuildCache 连接到 HTTP 生成缓存后端时，Gradle 不再关注重定向，而是将它们视为错误。从生成缓存后端获取重定向通常是配置错误（例如，使用“http”URL 而不是“https”），并且会对性能产生负面影响。

[4.4] 第三方依赖项升级

此版本包括几个第三方依赖项升级

jackson: 2.6.6 → 2.8.9
plexus-utils: 2.0.6 → 2.1
xercesImpl: 2.9.1 → 2.11.0
bsh: 2.0b4 → 2.0b6
bouncycastle: 1.57 → 1.58

此修复程序修复了以下安全问题

CVE-2017-7525（严重）
SONATYPE-2017-0359（严重）
SONATYPE-2017-0355（严重）
SONATYPE-2017-0398（严重）
CVE-2013-4002（严重）
CVE-2016-2510（高危）
SONATYPE-2016-0397（高危）
CVE-2009-2625（高危）
SONATYPE-2017-0348（高危）

Gradle 不公开这些第三方依赖项的 API，但自定义 Gradle 的用户需要了解这些依赖项。

此页面是否有用？