DriftLedger/docs/android-build-guide.md

Android 安装包打包与体积优化指南 (Android Build Guide)

在引入机器学习引擎（ONNX Runtime）及 React Native 新架构后，本项目的原生 C/C++ SO 库体积大幅增加。为避免将无意义的冗余架构包打包给最终手机用户，本项目对 Android 构建配置进行了专项体积优化。

本篇指南将为您介绍项目中的打包机制、优化细节，以及如何通过命令行进行差异化编译。

---

1. 体积优化核心原理

1.1 ABI 分包 (ABI Splits)

在 Android 系统的 build.gradle 中，我们启用了分包编译：

splits {
    abi {
        enable true
        reset()
        include "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
        universalApk true
    }
}

• 效果：系统会为每种 CPU 架构单独输出一个体积小巧的 APK，并额外保留一个兼容所有架构的通用包（Universal APK）。
• 独立包大小：~35MB - ~40MB
• 通用包大小：~140MB - ~170MB

1.2 默认编译架构限制

我们在 android/gradle.properties 中指定了默认编译目标为：

reactNativeArchitectures=arm64-v8a

• 为什么只包含 arm64-v8a：目前 99% 的主流现代 Android 实体机都是 64 位 ARM 架构（arm64-v8a）。在进行日常分发与本地 Release 测试时，默认只编译 arm64-v8a，能够省去编译另外 3 个架构的机器指令时间，编译速度提升 3~4 倍，且输出的包体最小。

1.3 Expo 持续原生生成 (Config Plugin) 的自动应用

Important

由于 android/ 目录被 Git 忽略，不要直接手动在其他设备上提交原生配置变更。 本项目已编写了专门的本地 Config Plugin：size-optimization。 当在新设备上重新 git clone 项目后，运行以下指令即可自动拉起 Config Plugin 并在重新生成的 android/ 目录中完美注入上述所有的体积优化配置（ABI 分包、默认单架构编译）：

npx expo prebuild --platform android

---

2. 编译命令与打包指令

请在项目的根目录（若已在 android/ 目录中则不需要前缀 cd android）执行以下指令：

2.1 本地测试/实体分发（仅编译 arm64-v8a，最快最推荐）

直接运行默认编译，会使用 gradle.properties 中配置 of arm64-v8a：

# 在 Windows Powershell 下执行：
$env:JAVA_HOME="C:\Program Files\Java\jdk-21"
$env:ANDROID_HOME="C:\Users\fmq\AppData\Local\Android\Sdk"
cd android
.\gradlew.bat :app:assembleRelease --offline --no-daemon

编译完成后，可在以下路径找到适合真机安装的轻量版 APK（约 37MB）：

• android\app\build\outputs\apk\release\app-arm64-v8a-release.apk

---

2.2 全量分包发布（适合多设备兼容测试/全网发布）

若需要同时生成适配所有手机架构的独立 APK 以及一个通用包，可以在命令行中通过参数覆盖默认架构：

$env:JAVA_HOME="C:\Program Files\Java\jdk-21"
$env:ANDROID_HOME="C:\Users\fmq\AppData\Local\Android\Sdk"
cd android
.\gradlew.bat :app:assembleRelease -PreactNativeArchitectures=armeabi-v7a,arm64-v8a,x86,x86_64 --offline --no-daemon

编译完成后，在输出目录会产生 5 个文件：

1. app-arm64-v8a-release.apk (推荐绝大多数真机，约 37MB)
2. app-armeabi-v7a-release.apk (适合极少数老旧真机)
3. app-x86-release.apk (适合 32 位模拟器)
4. app-x86_64-release.apk (适合 64 位模拟器)
5. app-universal-release.apk (包含上述全部架构的通用胖包，约 140MB)

---

2.3 模拟器专用打包 (x86_64)

若需要直接打包在 Windows/macOS 的 x86_64 原生安卓模拟器上测试：

.\gradlew.bat :app:assembleRelease -PreactNativeArchitectures=x86_64 --offline --no-daemon

即可秒级编译出专门针对模拟器的 app-x86_64-release.apk。

---

3. 高级优化项：Proguard/R8 与混淆 (选填)

如需进一步将独立包体积压缩到 25MB 左右，可以考虑在 gradle.properties 中开启混淆并做裁剪防御。

1. 在 gradle.properties 中添加：

   android.enableMinifyInReleaseBuilds=true
   android.enableShrinkResourcesInReleaseBuilds=true
   

2. 注意：由于引入了 ONNX Runtime 动态调用，如果运行崩溃，需要在 android/app/proguard-rules.pro 中加入如下混淆保留白名单：

   -keep class com.microsoft.onnxruntime.** { *; }
   -dontwarn com.microsoft.onnxruntime.**