一、安装前准备（必做）
- 设备与系统要求
- 仅支持 Android 系统，最低兼容 API 18（Android 4.3），建议 Android 7.0 及以上以获得完整功能。
- 电脑端需安装 Android SDK Platform Tools（含 adb），并配置环境变量，确保 cmd/powershell 中可执行
adb version。
- 开启开发者模式与 USB 调试
- 进入 "设置→关于手机→软件信息"，连续点击 "版本号 / 编译编号"7 次激活开发者模式。
- 返回设置首页，打开 "开发者选项"，开启 "USB 调试"；部分设备需开启 "USB 调试（安全设置）""USB 安装"。
- 连接电脑时，选择 "传输文件（MTP）" 模式，避免仅充电模式导致 adb 无法识别。
- 下载官方安装包
- 从 GitHub Releases（https://github.com/alipay/SoloPi/releases）下载最新版 SoloPi.apk，避免第三方来源以保障安全与稳定性。
二、安装步骤与权限授予（关键）
-
安装 APK
- 方法一（adb 安装，推荐）：连接设备后执行
adb install -r path/to/SoloPi.apk（-r 覆盖安装），出现 Success 即成功。 - 方法二（本地安装）：将 APK 传到手机，在文件管理器中打开，允许 "未知来源应用安装"（Android 8.0 + 需在应用权限中单独授权）。
- 方法一（adb 安装，推荐）：连接设备后执行
-
首次启动必授权项（缺一不可）
权限类型 授权操作 作用 ADB 权限 电脑执行 adb tcpip 5555，手机点击 "重试"建立无线调试连接，支持一机多控 悬浮窗权限 前往系统设置授予 "显示悬浮窗" 展示实时性能数据、操作面板 后台白名单 将 SoloPi 添加到系统后台保护名单 防止进程被系统回收，保障长时间运行 读写权限 授予存储权限 保存录制脚本、性能日志到 /sdcard/solopi 屏幕录制 / 相机权限 按需授予 支持录制回放、UI 自动化脚本录制
三、主流厂商特殊适配（避坑重点）
| 厂商 | 特殊设置 | 影响功能 |
|---|---|---|
| 小米 | 开启 "USB 安装""USB 调试（安全设置）"；在 SoloPi 应用权限中开启 "后台弹出界面" | 录制回放、一机多控 |
| 华为 | 开启 "仅充电模式下允许 ADB 调试" | 断开 USB 线后 adb 连接不中断 |
| VIVO | 开发者选项中开启 "USB 安全操作" | 录制回放、一机多控 |
| OPPO | 系统默认 10 分钟断开 USB 调试，需保持连接电脑或调整超时设置 | 长期性能测试稳定性 |
| 魅族 | 若测试支付 / 金融类应用，需在手机管家中关闭 "安全支付" | 录制回放时输入框正常操作 |
四、常见问题排查（快速解决）
- adb 无法识别设备
- 检查 USB 线是否正常，重新插拔或更换线缆。
- 确认设备已授权当前电脑调试（弹窗勾选 "一律允许此计算机"）。
- 安装对应品牌手机驱动（如华为手机助手、小米助手）。
- 安装失败提示 "INSTALL_PARSE_FAILED"
- 下载的 APK 损坏或版本不兼容，重新下载最新版。
- 设备系统版本低于 API 18，更换更高版本设备。
- 功能异常（如悬浮窗不显示、录制无响应）
- 重新检查悬浮窗、后台白名单等权限是否授予完整。
- 关闭系统安全输入法（设置→系统→语言和输入法），避免影响输入框操作。
- 重启 SoloPi 应用或设备，清除应用缓存后重试。
五、安装后验证
- 启动 SoloPi，检查悬浮窗是否正常显示。
- 执行
adb devices，确认设备状态为 "device"（无线调试时显示设备 IP:5555）。 - 测试基础功能（如录制一个简单操作并回放），验证权限与连接正常。
总结
安装的核心是完整授权 + 厂商适配 + adb 正常。按上述步骤操作，95% 的问题可避免；若仍有异常，优先检查权限与 adb 连接，再排查厂商特殊设置。