# java.lang.UnsatisfiedLinkError: dlopen 失败：找不到库 "libnative.so"

- **ID:** `android/unsatisfiedlinkerror-native-library-not-loaded`
- **领域:** android
- **类别:** runtime_error
- **验证级别:** ai_generated
- **修复率:** 85%

## 根因

原生库 (.so) 缺少、未打包到对应设备 ABI 的 APK 中，或因路径错误或二进制文件损坏导致加载失败。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Android 11 (API 30) | active | — | — |
| Android 12 (API 31) | active | — | — |
| Android 13 (API 33) | active | — | — |
| Android 14 (API 34) | active | — | — |

## 解决方案

1. ```
   将 .so 文件放入 app/src/main/jniLibs/<abi>/ 目录（例如 arm64-v8a），并在 build.gradle 中添加：sourceSets.main.jniLibs.srcDirs = ['src/main/jniLibs']
   ```
2. ```
   使用 Gradle ABI 过滤器：android.defaultConfig.ndk.abiFilters 'arm64-v8a', 'x86_64' 以仅包含支持的架构。
   ```
3. ```
   如果是第三方 SDK，使用 SDK 提供的集成方式（如 Maven 或 AAR）重新添加依赖，而不是手动放置 .so 文件。
   ```

## 无效尝试

- **** — The .so file is not automatically included in the APK unless the jniLibs source set is properly configured. (70% 失败率)
- **** — Modern Gradle requires the jniLibs directory or ABI splits; direct file references for native libs are not supported. (60% 失败率)
- **** — This flag prevents extracting native libs from the APK, but if the lib is already missing for the target ABI, it won't help. (50% 失败率)