本文介绍如何通过 gradle 的 files() 依赖声明方式，将本地 .jar 文件以资源形式纳入构建产物，实现离线环境下的多模块依赖共享，避免重复打包与远程仓库依赖。
本文介绍如何通过 gradle 的 files() 依赖声明方式，将本地 .jar 文件以资源形式纳入构建产物，实现离线环境下的多模块依赖共享，避免重复打包与远程仓库依赖。
在多模块 Java/Gradle 项目中，有时需要将某个通用工具库（如内部 SDK 或定制化组件）以原始 JAR 形式分发给多个子模块，并确保它们在运行时统一加载同一份最新版 JAR（而非各自 Shade 进去），同时支持完全离线构建。此时，不应使用 shaded 或 shadowJar 方式将依赖“打平”进主 JAR，而应将其作为可访问的资源文件嵌入最终产物，并由类加载器动态加载。
Gradle 提供了简洁可靠的机制来实现这一目标：使用 files() 声明文件依赖。该方式不触发远程仓库解析，完全基于本地路径，天然适配离线场景：
// build.gradle (Kotlin DSL 示例)
dependencies {
implementation(files("libs/shared-utils-1.2.0.jar"))
}
// build.gradle (Groovy DSL)
dependencies {
implementation(files("libs/shared-utils-1.2.0.jar"))
}
✅ 关键说明：
- files(...) 声明的 JAR 会自动加入编译与运行时 classpath，且 Gradle 会将其复制到 build/libs/ 输出目录中（若配合 application 或自定义 distZip 插件），也可通过 processResources 任务显式拷贝至 src/main/resources/ 下供运行时读取；
- 若需在运行时以 ClassLoader.getSystemResource() 或 getResourceAsStream() 加载该 JAR 中的资源（如配置文件、模板等），建议额外配置 copy 任务，确保其随主应用一同发布：
// 将指定 JAR 复制到最终资源输出目录（如 src/main/resources/lib/）
tasks.processResources {
from("libs/shared-utils-1.2.0.jar") {
into "lib"
rename { "shared-utils.jar" } // 统一命名便于运行时定位
}
}
对于多模块项目，只需在每个子模块的 build.gradle 中重复声明相同的 files(...) 依赖即可——Gradle 不会重复下载，也不会产生版本冲突，因为路径指向的是同一份本地文件。
⚠️ 重要注意事项：
- 不要尝试在运行时“比较 JAR 版本号并动态加载最新版”：这不仅增加复杂度，还易引发类加载隔离、签名验证失败、资源覆盖等问题；推荐由构建流程统一管控版本（如通过 CI/CD 更新 libs/ 目录 + Git 提交）；
- 若需彻底禁用网络请求（例如断网调试），可在执行时添加 --offline 参数：./gradlew build --offline；
- files(...) 依赖不会参与传递性依赖解析，因此它仅提供该 JAR 内部的类与资源，不自动拉取其自身的依赖项——如有需要，请手动补全或改用 flatDir 仓库（不推荐，已过时）。
综上，files() 是轻量、可靠、符合 Gradle 惯例的解决方案，兼顾离线性、可维护性与运行时灵活性，是共享本地 JAR 资源的最佳实践。
