flatDir 是 Gradle 明确不推荐的过时模式，因不支持元数据导致版本识别、传递依赖和冲突解析失效；AGP 4.2+ 强制警告，应改用 files() 或 fileTree()，并针对 AAR 手动处理资源与依赖。
flatDir 不是“不能用”，而是Gradle 明确不推荐、AGP（Android Gradle Plugin）持续警告、且在新项目中极易引发隐性故障的过时模式。它的问题不在语法报错，而在依赖解析逻辑层面彻底失效。
flatDir 为什么被 Gradle 官方标记为“should be avoided”
flatDir 的本质是让 Gradle 把一个本地文件夹当作“仓库”，但它不支持任何元数据格式（no metadata formats）——没有 pom.xml，没有 ivy.xml，也不读 META-INF/MANIFEST.MF。结果就是：
- Gradle 完全不知道你放进去的
.jar或.aar是哪个版本 -
无法识别其传递依赖：哪怕 AAR 内部
compileOnly了gson:2.10，flatDir引入后主工程照样要手动补这个依赖 -
无法做依赖冲突解析：两个不同模块引用了同名但不同内容的
utils.jar，Gradle 不会告警，只会随机选一个加载，运行时报NoClassDefFoundError或方法不存在 -
AGP 4.2+ 开始强制输出警告：
WARNING:: Using flatDir should be avoided because it doesn't support any meta-data formats.，且该警告无法关闭
这和 Maven 仓库或 mavenLocal() 的行为有根本差异：后者靠坐标（group:name:version）驱动解析，flatDir 靠文件名硬匹配，属于“盲引”。
files() 和 fileTree() 是更安全的替代方案
如果你只是想把本地 JAR/AAR 塞进 classpath，直接用 files() 或 fileTree() 即可，完全不需要 flatDir：
implementation files('libs/alipaySdk-15.5.7.aar')implementation fileTree(dir: 'libs', include: ['<em>.jar', '</em>.aar'])
它们不经过仓库解析流程，也就不会触发元数据缺失警告；更重要的是，它们不参与依赖图谱构建，所以你也不会误以为它们能带出传递依赖——这点反而更诚实。
注意：
-
files()是纯文件路径引用，不校验是否存在，拼错路径只会在编译期报错 -
fileTree()支持通配，但include模式里写'*.?ar'才能同时匹配.jar和.aar（因为?.ar会被当字面量处理）
AAR 本地引用必须额外处理资源与清单
AAR 不是 JAR，它含 res/、AndroidManifest.xml、R.txt、jni/ 等结构。仅靠 files() 引入后：
- 编译期会报
Resource not found：因为 Gradle 不自动解压 AAR 中的资源 -
android.sourceSets.main.jniLibs.srcDirs需显式指向libs/才能识别 SO 库 - 如果 AAR 用了
resourcePrefix，主工程未适配会导致资源引用失败
所以真正可靠的本地 AAR 引用，往往要配合：
android.sourceSets.main.jniLibs.srcDirs = ['libs']-
packagingOptions.pickFirst '*<em>/</em>.so'（防 SO 冲突） - 手动补全其 POM 中声明的 compileOnly 依赖（查 AAR 解压后的
public.txt或原始 module 的build.gradle）
flatDir 的坑不在“写不起来”，而在“看着能跑，上线后崩得没规律”。它绕过了 Gradle 依赖模型的核心约束，把本该由元数据保障的一致性，交给了开发者凭记忆维护。只要项目里还存在一个 flatDir 块，就等于在构建流程里埋了一颗不确定性的雷。
