Install with Options：重新定义Android应用安装体验

项目价值主张

在Android生态中，应用安装往往受限于系统权限与厂商定制，普通用户难以突破"仅允许官方商店安装"的枷锁。Install with Options借助Shizuku框架，让手机变身"口袋里的ADB工具"，无需连接电脑即可实现降级安装、测试包部署、多APK批量处理等高级操作。支持Android 7.0至最新系统，将开发者级安装能力装进你的口袋。

🔧 核心价值：突破系统限制的安装利器

🌟 五大核心能力

• 权限穿透技术
  通过Shizuku框架获取系统shell权限，就像拿到手机系统的"万能钥匙"，解锁普通安装器无法实现的高级功能。例如在Android 14上绕过"低目标SDK限制"，安装旧版应用而不被系统拦截。

• 多场景安装解决方案
  支持三种安装模式：单APK快速安装、多APK拆分包部署、批量应用静默安装。特别适合测试人员快速迭代应用版本，或用户迁移多应用场景。

• 风险控制机制
  内置安装状态实时监控（InstallStatus类），通过InstallResult反馈详细结果，失败时提供错误代码解析，就像给手术装上"实时监护仪"。

• 个性化安装参数
  提供20+可配置选项，从基础的"允许降级"到高级的"强制权限提示"，满足极客用户的定制需求。参数通过MutableOption类动态应用，如同给安装过程配备"精密调节器"。

• 跨版本兼容引擎
  自适应Android 7.0至14的系统差异，通过InternalInstaller和ShellInterface动态选择最佳安装路径，解决"新系统装旧应用"的兼容性难题。

🚀 典型应用场景

• 开发者测试流：无需反复插拔USB线，直接在设备上安装调试APK
• 旧应用续命：为不再更新的优质应用解除系统版本限制
• 多账户管理：支持为工作资料/访客用户定向安装应用
• 紧急恢复：在无法连接电脑时，通过OTG存储安装修复工具

🛠️ 技术解构：模块化交互架构

🔗 核心模块协作流程

用户交互层 ⟷ 业务逻辑层 ⟷ 系统接口层

1. 用户交互层
MainActivity作为交互入口，通过Compose UI构建直观操作界面。当用户选择APK文件后，DataModel.selectedFiles状态流触发文件解析流程，就像餐厅服务员记录点餐需求并传递给后厨。

2. 业务逻辑层
Installer类作为"总厨"，协调三大核心组件：

• ShizukuUtils：检查框架状态，确保"食材新鲜"（权限可用）
• ElevatedPermissionHandler：处理权限请求，如同"安全检查岗"
• InternalInstaller：执行实际安装操作，支持10+高级参数配置

3. 系统接口层
通过ShellInterface与RootInterface双接口设计，实现权限适配：

• 标准模式：Shizuku提供的shell权限（普通用户首选）
• 高级模式：通过libsu获取root权限（极客用户选项）

📦 关键技术组件解析

InstallStatus状态机
定义安装过程的"红绿灯系统"：

• SUCCESS：安装完成（绿灯）
• FAILURE：安装失败（红灯）
• PENDING：等待用户确认（黄灯）

通过广播接收器（INSTALL_STATUS_ACTION）实时更新UI，确保用户始终掌握安装进度，就像包裹配送的实时追踪系统。

MutableOption动态配置
采用"选项即对象"设计，每个安装参数（如ALLOW_DOWNGRADE）都是MutableOption子类实例，包含：

• 参数描述（titleRes/descRes）
• 系统兼容性标记（minSdk）
• 应用逻辑（apply()方法）

这种设计使新增选项如同"插件安装"般简单，开发者只需继承基类并实现两个方法。

📚 实践指南：从安装到精通

🚀 快速启动指南

环境准备

1. 安装Shizuku框架（如同给手机安装"权限扩展卡"）
2. 授予Shizuku权限（设置→应用→Shizuku→授予权限）
3. 启动Install with Options，完成初始配置

基础安装流程

// 核心代码简化版
val installer = rememberPackageInstaller(selectedFiles)
Button(onClick = { installer.install() }) {
    Text("开始安装")
}

1. 点击"选择文件"添加APK
2. 在选项面板勾选所需特性（如"允许降级"）
3. 点击安装按钮，等待结果提示

⚙️ 高级配置指南

gradle.properties调优
修改编译参数解决兼容性问题：

# 提升编译内存限制（解决大项目编译OOM）
org.gradle.jvmargs=-Xmx4096m -Dfile.encoding=UTF-8

# 启用非传递R类（减少编译时间）
android.nonTransitiveRClass=true

常用安装选项组合

• 旧应用安装：勾选"允许降级"+"绕过低目标SDK限制"
• 测试包部署：启用"允许测试包"+"禁用验证"
• 系统应用替换：需要root权限+"强制覆盖现有应用"

🐞 常见问题诊断

INSTALL_FAILED_VERSION_DOWNGRADE

• 问题本质：Android 14+加强了版本降级限制
• 解决方案：启用"允许降级"选项，若失败需root权限

Shell does not have permission

• 典型场景：工作资料/访客用户中安装
• 解决步骤：进入对应用户空间→开发者选项→启用调试功能

INSTALL_FAILED_NO_MATCHING_ABIS

• 根本原因：APK架构与设备不匹配（如x86设备安装ARM包）
• 排查方法：通过应用信息查看设备CPU架构，获取对应版本APK

📱 应用界面展示

丰富的安装参数配置面板，每个选项都配有详细说明

多APK安装实时进度监控，支持中途取消

安装失败时提供详细错误信息与解决方案建议

🔄 持续进化路线

项目通过Crowdin平台进行多语言协作（crowdin.yml配置），已支持20+语言。开发路线图重点包括：

• Android 15新特性适配
• AAB格式安装支持
• 安装脚本自定义功能

欢迎通过GitHub提交PR，或在Patreon支持项目持续开发。

开源地址：git clone https://gitcode.com/gh_mirrors/in/InstallWithOptions
许可协议：MIT（自由使用，二次开发需保留原作者信息）