fileTree 引入本地 JAR 不是真正依赖，仅添加编译路径，不生成元数据，导致 IDE 无法解析、无补全、运行时 ClassNotFoundException；应改用 flatDir + named dependency（如 implementation name: 'xxx'）。
直接用 fileTree 引入本地 JAR（比如 implementation fileTree(include: ['*.jar'], dir: 'libs')）能编译通过，但 IDE 里 import 报红、跳转不到类、运行时抛 ClassNotFoundException ——这不是你配置错了，是 Gradle 机制本身不支持这种写法做“真正依赖”。必须用 flatDir + 命名依赖，否则就是埋雷。
为什么 fileTree 不算真正的依赖
fileTree 只是把 JAR 解压后的内容加进编译 classpath，Gradle 不会为它生成依赖坐标、不参与依赖解析、不进构建缓存，IDE 也无法建立符号索引。后果包括：
- IntelliJ 中无法 import 类、无代码补全、Ctrl+Click 跳转失败
- 多模块项目中，其他模块声明
implementation project(':xxx')时，该 JAR 不会被传递下去 - 启用
configuration cache或build cache后，构建可能随机失败 - Spring Boot 的
bootJar任务默认不打包fileTree依赖的 JAR，导致运行时报错
正确写法：用 flatDir 注册本地仓库
在 build.gradle 里这样配：
repositories {
mavenCentral()
flatDir {
dirs 'libs' // 注意：路径是相对于 project root（即 build.gradle 所在目录）
}
}
dependencies {
implementation name: 'my-utils' // JAR 文件名是 my-utils.jar，这里不能带 .jar 后缀
implementation name: 'legacy-api', ext: 'jar' // ext 可显式指定，但通常省略也行
}
- 若 JAR 名为
external-sdk-2.1.0.jar，name必须写'external-sdk'，不是'external-sdk-2.1.0' -
dirs支持数组，如dirs 'libs', '../shared-libs'，但建议只用一个明确路径 - 不要和
fileTree共存——删掉所有旧的implementation fileTree(...)行
IntelliJ 必须手动重载项目
改完 build.gradle 后，IDE 不会自动感知变化：
- 在 IntelliJ 中点击右上角 Gradle 工具栏的 刷新按钮（或按
Ctrl+Shift+O） - 或者菜单选 File → Reload project
- 不重载的话，即使 Gradle 命令行构建成功，IDE 里依然报红、无法识别类
- 如果仍无效，可尝试 File → Invalidate Caches and Restart → Invalidate and Restart
验证是否真的生效
别只看 gradle build 成不成功，重点检查三件事：
- 在 Java 文件里写
import com.example.YourClassFromJar;—— IDE 没波浪线，且 Ctrl+Click 能跳进类定义（哪怕没源码，也能看到 jar:// 协议路径） - 运行
gradle dependencies --configuration runtimeClasspath，输出里应出现my-utils这一行 - 执行
gradle bootJar（Spring Boot 项目）后，解压build/libs/*.jar，确认BOOT-INF/lib/下有对应 JAR
最容易被忽略的是路径大小写和 name 与文件名的严格一致——macOS/Linux 下 MyUtils.jar 和 myutils.jar 是两个文件，写错就彻底找不到。
