本文旨在解决gradle升级至7.x及更高版本时，WAR任务中因configurations.compile配置废弃而导致的“未知属性’compile’”错误。文章将详细解释该问题产生的根源，并提供将class-Path属性从configurations.compile正确迁移至configurations.compileClasspath的解决方案，帮助开发者顺利完成Gradle项目升级，确保WAR文件清单的正确生成。
1. 问题背景与根源
在gradle项目升级过程中，特别是从旧版本（如gradle 4.x或更早版本）升级到gradle 7.x及更高版本时，开发者可能会遇到一个常见的构建失败错误：could not get unknown Property ‘compile’ for configuration container。此错误通常发生在gradle的war任务配置中，当尝试在war文件的manifest（清单）中动态生成class-path属性时，使用了已废弃或移除的configurations.compile。
例如，以下代码片段是导致此问题的典型场景：
war { archiveName 'xyz-svc-clt.war' manifest { attributes "Weblogic-Application-Version": getBuildVersion(), "Built-By": "${env.USERNAME}", "Built-On": new Date().format("yyyy-MM-dd'T'HH:mm:ssZ"), "Class-Path": configurations.compile.collect { it.getName() }.join(' ') // 错误源头 } // ... 其他配置 }
问题根源： Gradle从5.0版本开始，逐步废弃了传统的compile和runtime配置，并引入了更细粒度、意图更明确的依赖配置，如implementation、api、compileOnly、runtimeOnly等。这些新的配置旨在提供更优的构建性能和更清晰的依赖图。在Gradle 7.x及更高版本中，compile配置已彻底移除，不再可用。因此，任何直接引用configurations.compile的代码都会导致构建失败。
尽管implementation是compile在声明依赖时的主要替代品，但在某些特定场景下，例如在WAR清单中生成Class-Path，直接替换为configurations.implementation可能无法达到预期效果，甚至可能导致新的问题。这是因为implementation配置的依赖不会传递给消费者，并且它不直接代表一个可用于生成完整运行时类路径的聚合配置。
2. 解决方案：使用compileClasspath
针对在WAR清单中生成Class-Path属性的场景，Gradle提供了专门的配置来替代已移除的compile。正确的解决方案是使用configurations.compileClasspath。
compileClasspath配置代表了编译项目所需的完整类路径，包括直接依赖及其传递性依赖。对于WAR文件而言，其Class-Path属性通常需要包含所有运行时所需的JAR文件，而compileClasspath恰好提供了这样的集合。
将上述错误代码修改为以下形式即可解决问题：
war { archiveName 'xyz-svc-clt.war' manifest { attributes "Weblogic-Application-Version": getBuildVersion(), "Built-By": "${env.USERNAME}", "Built-On": new Date().format("yyyy-MM-dd'T':HH:mm:ssZ"), "Class-Path": configurations.compileClasspath.collect { it.getName() }.join(' ') // 解决方案 } if (isDev() == false){ rootSpec.exclude("**/*_log4j.xml") rootSpec.exclude("**/*.properties") } from('src/main/resources/'){ include 'handler-chain.xml' into 'WEB-INF/classes/com/abc/xyz/service/xyzService/' } from('src/main/resources/'){ include 'handler-chain.xml' into 'WEB-INF/classes/com/abc/xyz/service/xyzService/notification/' } }
通过将configurations.compile替换为configurations.compileClasspath，Gradle将能够正确解析并收集所有编译和运行时所需的依赖JAR文件名称，并将其拼接成Class-Path属性的值，从而消除构建错误，并确保WAR文件能够正确加载其依赖。
3. 注意事项与最佳实践
- 理解依赖配置的演变： 在Gradle升级过程中，理解其依赖管理模型的演变至关重要。旧的compile、runtime等配置已被更语义化的implementation、api、compileOnly、runtimeOnly、testImplementation等取代。在大多数情况下，你应该将dependencies块中的compile ‘group:artifact:version’替换为implementation ‘group:artifact:version’。
- compileClasspath与runtimeClasspath的区别：
- compileClasspath：用于编译源代码的类路径，包含implementation、api、compileOnly等配置的依赖及其传递性依赖。它通常包含了应用程序运行所需的所有核心依赖。
- runtimeClasspath：用于运行时所需的类路径，包含implementation、runtimeOnly等配置的依赖及其传递性依赖。在某些场景下，如果Class-Path仅需包含运行时独有的依赖（例如JDBC驱动），runtimeClasspath可能更合适。但对于大多数Web应用，compileClasspath通常足以满足Class-Path的需求，因为它包含了所有核心依赖。
- 在WAR清单中，通常需要的是一个能够使应用程序在容器中正确启动和运行的完整依赖列表，compileClasspath通常是更稳健的选择。
- 插件依赖： 确保项目中已正确应用了Java和war插件。这些插件提供了相应的任务和配置（包括compileClasspath）供WAR任务使用。
apply plugin: 'java' apply plugin: 'war'
- 逐步迁移： 对于大型或复杂的项目，建议在升级Gradle版本时，分阶段进行依赖配置的迁移和测试，以确保平稳过渡。
总结
在Gradle升级到7.x及更高版本时，configurations.compile的移除是导致构建失败的常见原因。通过将WAR任务中manifest的Class-Path属性从configurations.compile迁移到configurations.compileClasspath，可以有效解决此问题。理解Gradle依赖配置的演变及其不同配置的语义，是成功进行项目升级和维护的关键。遵循本文提供的解决方案和注意事项，将有助于开发者更顺利地适应Gradle的最新版本特性，确保项目的持续可构建性和稳定性。
