Android原生模块（Prefab）依赖构建失败排查求助

背景 #

你的Android应用包含40余个Android Library Module（ALM），每个模块通过externalNativeBuild+CMake构建C++共享库。原依赖逻辑：

• 依赖方ALM用api project(':lib')引用被依赖模块
• 依赖方CMake脚本手动通过add_library(SHARED IMPORTED)+相对路径引用被依赖.so

升级Gradle/AGP后，因并行构建时序问题出现liblib.so, needed by 'project', missing and no known rule to make it错误；改用官方推荐的Prefab管理原生依赖后，又碰到两类交替出现的问题：

1. Prefab执行报错：Directory ... is not readable
2. 链接错误undefined symbol ...，且CMake生成的配置将目标设为INTERFACE IMPORTED（仅头文件库类型），未设置IMPORTED_LOCATION

先解决Prefab目录不可读问题 #

问题根源 #

• 并行构建时序冲突：新版Gradle并行执行任务时，被依赖模块的Prefab包尚未生成，依赖模块就提前尝试读取目录，导致读取失败
• 被依赖模块未正确配置Prefab：未开启Prefab支持，或Prefab输出目录未正确暴露给依赖方
• 缓存损坏：build/intermediates下的Prefab缓存目录损坏，导致读取异常

修复步骤 #

1. 强制任务依赖顺序：在依赖模块的build.gradle.kts（或.gradle）中，让Prefab相关任务等待被依赖模块的Prefab生成任务完成后再执行。例如依赖:libA时添加：

   tasks.withType(com.android.build.gradle.tasks.PrefabTask) {
       dependsOn(project(':libA').tasks.named("prefabPublish"))
   }
   

2. 给被依赖模块配置正确的Prefab：在每个被依赖ALM的build.gradle.kts中开启Prefab并指定原生库信息：

   android {
       buildFeatures {
           prefab true
       }
       externalNativeBuild {
           cmake {
               // 让CMake将.so输出到Prefab可识别的目录
               arguments "-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=${project.buildDir}/intermediates/prefab/lib/main"
           }
       }
       // 自动识别异常时手动配置Prefab包
       prefab {
           create("libA") {
               headers = "src/main/cpp/include"
               libraryName = "libA"
           }
       }
   }
   

3. 清理缓存：执行./gradlew clean，删除build目录和.gradle/caches下的Prefab相关缓存，避免损坏缓存干扰构建

再解决CMake生成INTERFACE库、链接符号缺失问题 #

问题根源 #

• 被依赖模块的Prefab包未包含.so：Prefab默认仅收集头文件，若未明确配置库路径，会被识别为仅头文件的INTERFACE库
• 依赖模块CMake脚本写法错误：未使用Prefab标准的find_package引用方式，仍沿用手动添加IMPORTED库的老逻辑
• ABI不匹配：依赖模块与被依赖模块的构建ABI不一致，导致Prefab找不到对应ABI的.so文件

修复步骤 #

1. 确保被依赖模块的Prefab包包含.so：在被依赖模块的build.gradle.kts中明确指定库路径，或让Prefab自动读取CMake输出：

   prefab {
       create("libA") {
           headers = "src/main/cpp/include"
           // 单ABI场景指定库路径
           libraryPath = "build/intermediates/prefab/lib/main/${android.defaultConfig.ndk.abiFilters.first()}"
           // 多ABI场景按变体配置
           variants {
               create("debug") {
                   libraryPath = "build/intermediates/prefab/lib/debug/${android.defaultConfig.ndk.abiFilters.first()}"
               }
               create("release") {
                   libraryPath = "build/intermediates/prefab/lib/release/${android.defaultConfig.ndk.abiFilters.first()}"
               }
           }
       }
   }
   

2. 修改依赖模块的CMake脚本：改用Prefab标准引用方式，替换手动添加IMPORTED库的代码：

   # 删除原手动添加IMPORTED库的代码
   find_package(libA REQUIRED CONFIG)
   target_link_libraries(你的库名 PRIVATE libA::libA)
   

3. 统一所有模块的ABI配置：在项目根目录的build.gradle.kts中为所有ALM设置统一的ABI过滤，避免ABI不匹配：

   subprojects {
       afterEvaluate {
           if (plugins.hasPlugin("com.android.library")) {
               android {
                   defaultConfig {
                       ndk {
                           abiFilters("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
                       }
                   }
               }
           }
       }
   }
   

4. 检查依赖声明：确保依赖模块使用api project(':libA')或implementation project(':libA')，让Gradle自动传递Prefab依赖信息

额外排查技巧 #

• 临时禁用并行构建：若问题仍存在，可在gradle.properties中设置org.gradle.parallel=false，确认是否为并行构建时序问题，再针对性调整任务依赖
• 升级NDK与CMake：确保NDK版本与当前AGP兼容（如AGP 8.x对应NDK 25+），CMake使用AGP推荐版本（在android.externalNativeBuild.cmake.version中指定），避免兼容性问题
• 检查Prefab输出：查看被依赖模块的build/intermediates/prefab目录，确认是否生成了包含头文件和.so的完整包

内容的提问来源于stack exchange，提问作者marczellm