本文介绍如何通过 Gradle 将本地 .jar 文件以“文件依赖”方式引入项目，并确保其被正确打包进最终的可执行 JAR 中，适用于离线环境及多模块间共享第三方库的场景。
本文介绍如何通过 gradle 将本地 `.jar` 文件以“文件依赖”方式引入项目，并确保其被正确打包进最终的可执行 jar 中，适用于离线环境及多模块间共享第三方库的场景。
在 Gradle 构建体系中，若需复用一个已预先下载或构建完成的本地 JAR 文件（例如跨多个子项目共享的工具包、内部 SDK 或离线依赖），最直接且可靠的方式是使用 files() 声明文件依赖（File Dependencies），而非依赖远程仓库坐标。这种方式完全绕过 Maven/Gradle 仓库解析，天然支持离线构建，也避免了版本冲突、重复 shading 或运行时类加载歧义等问题。
✅ 正确做法：声明 files() 依赖并确保打包进最终 JAR
默认情况下，implementation(files(...)) 仅将该 JAR 加入编译与运行时 classpath，但不会自动将其复制到最终生成的 fat JAR 或 resources 目录中。若目标是“让 dependency.jar 成为最终 JAR 的一个内嵌资源（如放在 /lib/ 下供运行时动态加载）”，则需额外配置 processResources 或 jar 任务：
// build.gradle (Groovy DSL)
dependencies {
implementation files('libs/my-shared-lib.jar') // 放在项目根目录下的 libs/ 文件夹中
}
// 确保该 JAR 被复制进最终 JAR 的 /lib/ 目录下
jar {
from {
configurations.runtimeClasspath.files.findAll { it.name.endsWith('.jar') && it.name != project.archivesBaseName + '.jar' }
.collect { zipTree(it) }
} into 'lib/'
// 或更精准地只复制指定文件（推荐）：
from('libs/my-shared-lib.jar') {
into 'lib/'
rename { 'shared-lib.jar' } // 可选：重命名避免冲突
}
}? 提示：上述 jar { ... } 配置会将 my-shared-lib.jar 打包至最终 JAR 的 lib/ 子目录中。你可在运行时通过 getClass().getResource("/lib/shared-lib.jar") 获取其路径，并用 URLClassLoader 动态加载。
⚠️ 注意事项与最佳实践
- 路径应相对且可移植：建议将 JAR 放在项目内的 libs/ 目录下（如 ./libs/my-shared-lib.jar），避免硬编码绝对路径，便于团队协作与 CI 构建。
- 不推荐运行时“版本择优加载”逻辑：原文中提到“加载最新版 dependency.jar”——这极易引发类加载器隔离、资源覆盖、签名冲突等不可控问题。Gradle 的职责是确定性构建，运行时动态加载应作为明确设计决策，而非替代依赖管理。
- 多模块复用？统一声明更安全：若多个子项目需共用同一 JAR，可在根 build.gradle 中定义 ext.sharedJar = file('libs/my-shared-lib.jar')，各子模块通过 implementation files(rootProject.ext.sharedJar) 引用，保证一致性。
- 离线构建保障：执行 ./gradlew build --offline 可强制 Gradle 完全跳过网络请求；只要所有依赖（包括 files(...) 指向的文件）已存在，构建即能成功。
✅ 替代方案对比（不推荐但需知）
| 方案 | 是否离线友好 | 是否可打包为资源 | 风险点 |
|---|---|---|---|
| implementation files(...) + 自定义 jar 任务 | ✅ 是 | ✅ 是 | 推荐，可控性强 |
| compileOnly files(...) | ✅ 是 | ❌ 否（不参与打包） | 编译可用，但运行时缺失 |
| flatDir 仓库 + name 依赖 | ⚠️ 半离线（需初始化） | ❌ 否（需额外 copy） | 已被 Gradle 官方标记为过时（deprecated），不推荐新项目使用 |
综上，files() + 显式 jar.from() 是最简洁、标准、可维护的解决方案。它既满足离线需求，又赋予你对资源位置与结构的完全控制权，契合专业构建流程的设计哲学。
