React Native从0.71.8升级到0.76.5后Android端出现libhermes_executor.so缺失错误

问题描述 #

升级React Native从0.71.8到0.76.5后，Android设备运行应用时抛出以下错误：

java.lang.UnsatisfiedLinkError: dlopen failed: library "libhermes_executor.so" not found at java.lang.Runtime.loadLibrary0 (Runtime.java:1081) 
at java.lang.Runtime.loadLibrary0 (Runtime.java:1003)
at java.lang.System.loadLibrary (System.java:1765)
at com.facebook.soloader.nativeloader.SystemDelegate.loadLibrary(SystemDelegate.java:24)

当前相关配置：

• Gradle插件版本：classpath('com.android.tools.build:gradle:8.6.0')
• Android构建参数：

  minSdkVersion = 24
  compileSdkVersion = 34
  targetSdkVersion = 34
  

解决方法 #

1. 确认Hermes启用状态 #

检查android/app/build.gradle中是否正确启用Hermes：

project.ext.react = [
  enableHermes: true, // 确保此处为true
]

同时确认dependencies块中包含Hermes依赖：

implementation project(':hermes-engine')

2. 清理缓存并重新构建 #

执行以下命令彻底清理项目缓存并重新构建：

# 清理Android构建缓存
cd android && ./gradlew clean
# 清理Node依赖与缓存
rm -rf node_modules && npm install
# 带清理参数重新运行Android项目
npx react-native run-android --clean

3. 检查Soloader初始化 #

确保MainApplication.java中正确初始化Soloader（React Native 0.7x版本依赖该库加载原生库）：

import com.facebook.soloader.SoLoader;

@Override
public void onCreate() {
  super.onCreate();
  SoLoader.init(this, /* native exopackage */ false);
  // 其他初始化逻辑
}

4. 验证ABI过滤配置 #

如果项目设置了ABI过滤，需确保包含Hermes支持的架构，在android/app/build.gradle的defaultConfig中检查：

ndk {
  abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64' // Hermes默认支持的架构集合
}

避免遗漏必要ABI导致对应架构设备找不到库文件。

5. 手动复制Hermes库文件（兜底方案） #

若以上方法无效，可手动复制Hermes的so文件到项目目录：

1. 找到node_modules/hermes-engine/android/lib下对应ABI的libhermes_executor.so文件
2. 将文件复制到android/app/src/main/jniLibs/[对应ABI]/目录（若jniLibs目录不存在则创建）
3. 重新执行构建命令

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