本文详解如何通过 Gradle 的 providedRuntime 配置与自定义 Copy 任务，将指定模块（如 tomcatLib 及其传递依赖）从 WAR 包中排除，并自动复制到 Tomcat 的 lib/ 目录，实现共享库的集中管理。
本文详解如何通过 gradle 的 `providedruntime` 配置与自定义 copy 任务，将指定模块（如 `tomcatlib` 及其传递依赖）从 war 包中排除，并自动复制到 tomcat 的 `lib/` 目录，实现共享库的集中管理。
在典型的 Java Web 多项目构建中，常需将某些通用库（如日志框架、工具包或自定义中间件）部署到 Tomcat 的全局 lib/ 目录，而非打包进每个 WAR 文件。这样既能避免重复依赖、减小 WAR 体积，又能实现类加载器层级的统一管理（例如让 webApp 与 tomcatLib 共享同一份 commons-text 实例）。Gradle 原生支持这一场景，关键在于正确使用 providedRuntime 依赖配置并显式声明依赖排除逻辑。
✅ 正确配置 providedRuntime 排除 WAR 打包
Gradle 的 war 插件默认提供两个“已提供”（provided）配置：providedCompile（编译期可见，不打包）和 providedRuntime（运行期由容器提供，不打包）。二者均不会出现在 WEB-INF/lib/ 中，但 providedRuntime 更符合 Tomcat 全局库语义（因 Tomcat 启动时会将其加入 classpath）。
以你的项目结构为例，在 webApp 模块的 build.gradle 中应这样声明：
plugins {
id 'war'
}
dependencies {
// 这些将被排除出 WAR，但参与编译和运行期解析
providedRuntime project(':tomcatLib') // 排除 tomcatLib.jar 及其传递依赖（如 regularLibA、commons-text）
providedRuntime 'org.apache.commons:commons-lang3:3.12.0' // 若 commons-lang3 也需全局化，同样声明
// 其余正常打包的依赖（如 regularLibB）
implementation project(':regularLibB')
// 注意：不要对 regularLibA 再单独声明 —— 它已被 tomcatLib 的传递依赖覆盖，且受 providedRuntime 约束
}
⚠️ 关键注意事项：
- providedRuntime project(':tomcatLib') 会递归排除 tomcatLib 的所有运行时依赖（包括 regularLibA 和 commons-text），因此无需再为它们单独添加 providedRuntime；
- 若 regularLibB 也依赖 commons-text，但你不希望它被排除，则必须确保 regularLibB 对 commons-text 的依赖未被 providedRuntime 覆盖（即 regularLibB 自身不声明 providedRuntime 该依赖，且 webApp 不重复声明）；
- providedCompile 仅影响编译期 classpath，providedRuntime 才真正控制 WAR 打包行为，务必优先使用后者。
? 自动复制 JAR 到 Tomcat lib 目录
排除后，需将 tomcatLib.jar 及其实际所需的依赖（如 regularLibA.jar、commons-text-1.10.0.jar）复制到目标 Tomcat 的 lib/ 目录。Gradle 提供了灵活的 Copy 任务，可精准收集 providedRuntime 配置下的所有文件：
// 在 webApp/build.gradle 中追加
task copyToTomcatLib(type: Copy) {
// 定义目标目录（可根据环境变量或属性动态设置）
def tomcatLibDir = file("$project.rootDir/../tomcat/apache-tomcat-9.0.83/lib")
from configurations.providedRuntime
into tomcatLibDir
// 可选：仅复制本项目直接声明的 providedRuntime 依赖（排除 transitive），用以下方式替代 from 行：
// from configurations.providedRuntime.resolvedConfiguration.files { it.name.startsWith('tomcatLib') || it.name.startsWith('regularLibA') }
// 可选：打印即将复制的文件列表，便于调试
doLast {
println "Copying to Tomcat lib: ${configurations.providedRuntime.files}"
}
}
// 将 copyToTomcatLib 设为 build 的依赖（可选）
// build.dependsOn copyToTomcatLib
执行 ./gradlew :webApp:copyToTomcatLib 即可完成复制。你还可以结合 Gradle 属性（如 -PtomcatHome=/opt/tomcat）提升可移植性：
def tomcatHome = project.findProperty('tomcatHome') ?: "$project.rootDir/../tomcat"
def tomcatLibDir = file("$tomcatHome/lib")
? 验证与最佳实践
- 验证 WAR 结构：运行 ./gradlew :webApp:war 后解压 webApp/build/libs/webApp.war，确认 WEB-INF/lib/ 中不再包含 tomcatLib.jar、regularLibA.jar 和 commons-text-*.jar；
- 验证类加载：启动 Tomcat 时，确保 tomcatLib 中的类能被 webApp 的 Servlet 正常调用（若出现 ClassNotFoundException，检查 providedRuntime 是否遗漏依赖，或 Tomcat lib/ 目录权限）；
-
版本一致性：全局库建议使用 strictly 版本约束，避免多模块间版本冲突：
providedRuntime('org.apache.commons:commons-text') { version { strictly '1.10.0' } }
通过以上配置，你不仅实现了 WAR 的精简与依赖解耦，还建立了可复用、可审计的 Tomcat 共享库部署流程——这是企业级 Java Web 应用构建中的重要工程实践。
