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

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

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

---

## 1. 体积优化核心原理

### 1.1 ABI 分包 (ABI Splits)
在 Android 系统的 `build.gradle` 中，我们启用了分包编译：
```groovy
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` 中指定了默认编译目标为：
```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](file:///c:/Users/fmq/Documents/work/beancount-mobile/plugins/size-optimization/app.plugin.js)。
> 当在新设备上重新 `git clone` 项目后，运行以下指令即可自动拉起 Config Plugin 并在重新生成的 `android/` 目录中完美注入上述所有的体积优化配置（ABI 分包、默认单架构编译）：
> ```bash
> npx expo prebuild --platform android
> ```

---

## 2. 编译命令与打包指令

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

### 2.1 本地测试/实体分发（仅编译 arm64-v8a，最快最推荐）
直接运行默认编译，会使用 `gradle.properties` 中配置 of `arm64-v8a`：
```powershell
# 在 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 以及一个通用包，可以在命令行中通过参数**覆盖默认架构**：
```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 -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 原生安卓模拟器上测试：
```powershell
.\gradlew.bat :app:assembleRelease -PreactNativeArchitectures=x86_64 --offline --no-daemon
```
即可秒级编译出专门针对模拟器的 `app-x86_64-release.apk`。

---

## 3. 高级优化项：Proguard/R8 与混淆 (选填)
如需进一步将独立包体积压缩到 25MB 左右，可以考虑在 `gradle.properties` 中开启混淆并做裁剪防御。
1. 在 `gradle.properties` 中添加：
   ```properties
   android.enableMinifyInReleaseBuilds=true
   android.enableShrinkResourcesInReleaseBuilds=true
   ```
2. 注意：由于引入了 `ONNX Runtime` 动态调用，如果运行崩溃，需要在 `android/app/proguard-rules.pro` 中加入如下混淆保留白名单：
   ```proguard
   -keep class com.microsoft.onnxruntime.** { *; }
   -dontwarn com.microsoft.onnxruntime.**
   ```