📚 课程目录第2章 So库加载失败

So 库加载失败：arm64/x86 架构兼容性问题排查

So 库加载失败，这在 SDK 集成中太常见了。我记得刚接触 SDK 集成那会儿，被这个问题折腾得一宿没睡。

说白了就是：你的 App 打包时少带了某些架构的 so 库，或者带错了版本。结果用户一装上去，直接崩溃。更麻烦的是，这种崩溃还不是必现的——只有在特定 CPU 架构的设备上才会触发。我自己就踩过这个坑，所以今天专门聊聊这个事儿。

先搞清楚：什么是 ABI？为什么架构这么重要？

ABI 全称是 Application Binary Interface。你可以把它理解为 App 和 CPU 之间的「翻译官」。不同品牌的手机用着不同架构的 CPU，翻译官的语言就不一样。

目前主流的有这几种：

arm64-v8a：几乎所有近几年的旗舰机、中端机都在用。64 位，主流中的主流。
armeabi-v7a：一部分老机型还在用。32 位，兼容性上其实挺好。
x86 / x86_64：多见于模拟器，还有一些平板。真实用户少，但测试环境容易碰到。
armeabi：早该淘汰了。我强烈建议你直接放弃它。兼容性差，性能还拉胯。

我在项目中遇到过几次诡异的问题：某款 So 库只在部分小米设备上崩溃，原因是那款机型的系统是 64 位内核，但 App 只带了 32 位的 so 库，运行时就报找不到符号。

架构兼容性，一张表说明白

ABI 名称	CPU 架构	位数	常见设备	备注
arm64-v8a	AArch64	64 位	2020 年后大多数 Android 手机	优先适配
armeabi-v7a	ARMv7	32 位	部分老机型 / 低端设备	建议保留以兼容
x86	IA-32	32 位	模拟器 / 部分平板	测试用途为主
x86_64	AMD64/Intel 64	64 位	新模拟器 / 部分 Chromebook	可酌情保留
armeabi	ARMv5/ARMv6	32 位	极老机型	强烈不建议使用

警告：当你只打包了 armeabi-v7a，但在 arm64-v8a 设备上运行时，Android 系统会尝试用 32 位兼容模式加载。如果你的 so 库里有部分 native 代码依赖 64 位运行环境，那就直接崩给你看。我曾经遇到过一个案例：某个编码库的 so 在 arm64 设备上加载时，JNI 调用直接抛 UnsatisfiedLinkError，排查了三个小时才发现是少放了 arm64-v8a 的 so。

通过打包产物诊断：到底缺了哪个 so？

排查的第一步，是看看你的 APK 里到底放了哪些 so 文件。很简单，用压缩工具打开 APK，直奔 lib/ 目录。

# 解压 APK 并查看 lib 目录结构示例
unzip -l your_sdk.apk | grep lib/

# 输出表现应该是类似这样的结构：
# lib/arm64-v8a/libnative_sdk.so
# lib/armeabi-v7a/libnative_sdk.so
# lib/x86_64/libnative_sdk.so

我个人习惯是先确认 arm64-v8a 和 armeabi-v7a 这两个目录是不是都完整。只要有一个目录里缺了对应的 so 文件，或者根本没有这个目录——那问题就找到了。

你想想看，如果只打了 armeabi-v7a，那 arm64 设备肯定跑不起来。反过来，只打 arm64-v8a，老设备照样报错。

你的 build.gradle 配置错了没？

最常见的配置错误出现在 ndk.abiFilters。很多开发者想偷懒省包体积，结果把自己坑了。

android {
    defaultConfig {
        ndk {
            // 正确做法：同时保留 arm64-v8a 和 armeabi-v7a
            abiFilters "arm64-v8a", "armeabi-v7a"

            // ❌ 错误做法：只保留一个，兼容性极差
            // abiFilters "arm64-v8a"
        }
    }
}

为什么我强调这个？因为我有个同事曾经就写了 abiFilters "arm64-v8a"，然后他测试的时候用的自己的手机，一切正常。结果一上线，一群用老机型的用户直接闪退。嗯，注意这里：如果 App 有多个 so 库，它们的架构必须统一。不能这个 so 是 arm64，那个 so 只有 v7a，那跑起来还是会出问题。

小提示：如果你拿不准到底要放哪些架构，最简单的方式是去 Google Play Console 或者你产品的崩溃统计平台看一下「受影响设备」的 CPU 架构分布。我建议优先保留 arm64-v8a 和 armeabi-v7a，x86 系列只在模拟器上测一下就足够了。

如何修复？分步骤来

检查 SDK 文档：看看它到底支持哪些 ABI。有些 SDK 明确说了只支持 arm64-v8a，那你就别勉强塞 armeabi-v7a。我在项目中遇到过，明明只支持 arm64，硬塞 v7a 的 so 进去还报错。
确认打包策略：决定是「全量打包」还是「按需分发」。可以使用 Android App Bundle 或 APK split 按 ABI 拆包，这样不同设备只下载对应架构的 so，包体积也能控制住。
手动补充缺失的 so：如果 SDK 没有提供某个架构的 so，联系第三方或者自己编译。别伪造 so 文件，那只会崩得更诡异。我以前试过把 v7a 的 so 重命名为 arm64-v8a 放进去……结果自然是崩溃得更怪异。
验证修复结果：用真机或模拟器，分别在不同架构的设备上跑一遍。用 adb 安装并观察日志，看日志里是否还有 UnsatisfiedLinkError 或 dlopen failed: library “xxx.so” not found。

我建议你可以这么验证：找一台 arm64 设备（比如近两年的小米、OPPO、vivo），再找一台老一点的 armeabi-v7a 设备。两台上都跑一遍 App 的 native 功能。如果都没问题，那大概率架构兼容性这块就稳了。

避坑指南

不要只打 armeabi：这架构太老了。部分 64 位设备不兼容，性能还差。省那点体积不值得。
别私自修改 so 文件名：so 文件的加载依赖内部符号表。改名等于自杀。我之前遇到过改名字后加载成功但调用方法就崩溃的，异常难排查。
混合架构要统一：所有 so 都必须同一个架构。你说你 arm64 的 libA.so 加 v7a 的 libB.so，跑起来不崩才有鬼。
检测工具：可以用 adb shell getprop ro.product.cpu.abi 查看设备的 ABI，用 adb shell ls /system/lib/ 看系统有哪些 so，对比一下就清楚了。

再看看这张图：So 架构兼容性排查全流程

下面我把排查思路画成了一张流程。你跟着走一遍，基本不会漏。

So 库加载失败的原因其实就那几个方向。只要按着这张图的思路一步步来，基本不会漏掉关键点。