升级Gradle 7.x时:app:mergeDebugNativeLibs任务执行失败排查咨询

云原生阿岚

2026-9-1

问题核心成因

该报错是Gradle 7.x 适配React Native Turbo/Fabric新架构时的典型问题，本质是mergeDebugNativeLibs任务执行阶段检测到重复的原生so库文件，Gradle 7.x 对原生库文件的重复校验规则远严格于旧版本，常见触发原因：

新架构底层C++运行时依赖的libc++_shared.so、libjsi.so等核心so被多个依赖重复打包：React Native核心包会自带这些so，未适配新架构的第三方原生库、手动link的旧原生模块往往也会内置一份版本不匹配的同名so，触发冲突
旧版本Gradle配置的so排除规则在Gradle 7.x下语法失效，没有正确处理重复文件
React Native Gradle插件版本和当前Gradle版本、RN版本不匹配，新架构的原生库合并逻辑未正常生效
本地构建缓存残留，旧架构编译生成的so文件混入新架构构建流程

可落地修复步骤

按顺序执行，每步完成后可先执行构建验证，无需一次做完所有步骤：

修正android/app/build.gradle中的打包规则，替换旧的packagingOptions配置为Gradle 7.x兼容的写法，优先选择第一个匹配的so文件而非直接排除，避免出现架构缺失问题：

android {
    // 保留你原有其他配置项
    packagingOptions {
        pickFirst 'lib/**/libc++_shared.so'
        pickFirst 'lib/**/libjsi.so'
        pickFirst 'lib/**/libreactnativejni.so'
        // 如果后续构建仍提示其他so重复，按上述格式追加对应规则即可
    }
}

禁止使用旧教程中写死CPU架构的exclude规则（比如exclude 'lib/arm64-v8a/libc++_shared.so'），这类写法会导致对应架构设备启动时找不到so库直接闪退

统一全局依赖版本，避免第三方依赖拉取不匹配的RN原生包，在android/build.gradle中添加强制版本规则：

allprojects {
    // 保留原有其他配置
    configurations.all {
        resolutionStrategy {
            force "com.facebook.react:react-native:${rootProject.ext.reactNativeVersion}"
        }
    }
}

同时确认android/gradle.properties中新架构相关配置正确：

newArchEnabled=true
# 若使用Hermes引擎则保持开启，否则设为false
hermesEnabled=true

全量清理构建缓存，排除旧产物干扰：
在项目根目录执行以下命令：

# 清理Gradle构建产物
cd android && ./gradlew clean && cd ..
# 删除本地依赖和全局Gradle缓存
rm -rf node_modules && rm -rf ~/.gradle/caches
# 重新安装依赖
npm install # 用yarn/pnpm的话替换为对应安装命令即可
# 重新触发debug构建
cd android && ./gradlew assembleDebug

若上述步骤执行后仍报错，逐个排查第三方原生依赖：

暂时注释掉所有超过1年未更新、未明确标注支持RN新架构的原生依赖，逐个重新引入定位冲突来源
对必须保留但未适配的依赖，可在对应依赖的build.gradle中移除其内置的C++运行时so打包逻辑，避免重复带入冲突文件

无效方案避坑

以下常见公开方案无法从根本解决问题，无需浪费时间尝试：

直接关闭新架构回退到旧架构，属于回避问题而非解决
将Gradle降回6.x版本，会导致Turbo/Fabric新架构无法正常编译运行
手动删除node_modules下依赖内的so文件，重新安装依赖后会恢复，无法持久生效

修复验证标准：执行到:app:mergeDebugNativeLibs任务时不再抛出duplicate file类错误，最终生成的debug安装包可正常启动，新架构特性可正常调用。

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