Appium 在小米平板上的安装受限与闪退排查

Appium 在小米平板上的安装受限与闪退排查

• • 背景
  • 典型报错一：安装失败
  • • 典型错误
    • 含义
    • [Appium 为什么要安装这些辅助工具](#Appium 为什么要安装这些辅助工具)
  • 安装失败时的排查步骤
  • • [1. 开启"USB 安装"](#1. 开启“USB 安装”)
    • [2. 盯住手机/平板屏幕弹窗](#2. 盯住手机/平板屏幕弹窗)
    • [3. 关闭 USB 安装校验](#3. 关闭 USB 安装校验)
    • [4. 关闭 Google Play Protect 扫描](#4. 关闭 Google Play Protect 扫描)
  • 手动安装测试
  • [典型报错二：Appium Settings 启动即闪退](#典型报错二：Appium Settings 启动即闪退)
  • • 现象
    • 小米系统上的常见原因
  • 小米系统专项处理
  • • [1. 开启自启动](#1. 开启自启动)
    • [2. 关闭省电限制](#2. 关闭省电限制)
    • [3. 开启后台弹出界面](#3. 开启后台弹出界面)
    • [4. 保持设备常亮、解锁](#4. 保持设备常亮、解锁)
  • [清理 Appium 相关残留](#清理 Appium 相关残留)
  • 最关键的"真死因"：定位前台服务权限
  • • 这说明什么
    • 大白话解释
  • [ADB 强制授权](#ADB 强制授权)
  • 手动在系统设置中授予定位权限
  • [建议的 Appium Capability](#建议的 Appium Capability)
  • • 含义
  • 完美解决
  • [针对 Flutter 应用的额外提醒](#针对 Flutter 应用的额外提醒)
  • 一键排查思路

背景

在使用 Appium Inspector 或 Appium UiAutomator2 驱动连接小米平板时，常见会遇到以下两类问题：

1. Appium 辅助 APK 安装失败
2. Appium Settings 已安装，但启动后立即闪退

这类问题在小米 / Redmi / OPPO / VIVO / 华为 等国产系统上尤其常见，根本原因通常不是 Appium 本身，而是：

• 系统默认限制通过 USB 安装应用
• 系统对后台服务、前台服务和定位权限限制更严格
• MIUI / HyperOS 对后台辅助工具有较强的清理和拦截行为

典型报错一：安装失败

典型错误

[INSTALL_FAILED_USER_RESTRICTED: Install canceled by user]

含义

Appium 在尝试向设备安装必要辅助工具时，被系统拦截，或者用户没有在设备弹窗中点击"允许"。

Appium 为什么要安装这些辅助工具

Appium 会在设备上安装一些辅助 APK，例如：

• io.appium.settings
• io.appium.uiautomator2.server
• io.appium.uiautomator2.server.test

这些组件用于：

• 修改系统设置
• 协助 UiAutomator2 驱动工作
• 处理网络、定位、辅助权限等自动化动作

如果这些辅助包装不上，Session 无法建立。

安装失败时的排查步骤

1. 开启"USB 安装"

仅开启 USB 调试 通常不够，还需要：

• 设置 -> 开发者选项 -> USB 安装

说明：

• 小米设备开启此项时，可能要求登录小米账号并插入 SIM 卡

2. 盯住手机/平板屏幕弹窗

点击 Start Session 后，设备上常会弹出类似提示：

• 是否允许通过 USB 安装应用
• 是否允许安装 Appium Settings

必须在倒计时结束前点击：

• 允许
• 确认

3. 关闭 USB 安装校验

在开发者选项中，尝试关闭：

• 验证通过 USB 传输的应用
• 检查通过 ADB 安装的应用

4. 关闭 Google Play Protect 扫描

如果设备带 Google 服务框架，可尝试：

• Play 商店 -> 头像 -> Play Protect -> 设置
• 关闭设备扫描安全威胁

手动安装测试

可以先用 adb 手工验证是否有安装权限：

adb install "C:\Users\onese\.appium\node_modules\appium-uiautomator2-driver\node_modules\io.appium.settings\apks\settings_apk-debug.apk"

如果手工安装都失败，说明问题在设备系统权限，而不是 Appium Inspector。

典型报错二：Appium Settings 启动即闪退

现象

• Appium Settings 已成功安装
• 但一打开就闪退
• Appium Session 无法建立

小米系统上的常见原因

小米 / HyperOS 对后台辅助应用控制很严格，经常会把 Appium Settings 判定为异常后台进程并直接杀掉。

小米系统专项处理

1. 开启自启动

路径通常为：

• 手机管家 / 安全中心 -> 应用管理 -> 权限管理 -> 自启动管理

找到：

• Appium Settings

并开启自启动。

2. 关闭省电限制

进入：

• 设置 -> 应用管理 -> Appium Settings -> 省电策略

设置为：

• 无限制

3. 开启后台弹出界面

进入：

• 设置 -> 应用管理 -> Appium Settings -> 权限管理

开启：

• 后台弹出界面
• 显示悬浮窗

4. 保持设备常亮、解锁

因为某些系统在息屏或锁屏时，会切断 ADB 相关后台进程。

清理 Appium 相关残留

如果怀疑旧包冲突，可以先彻底卸载：

adb uninstall io.appium.settings
adb uninstall io.appium.uiautomator2.server
adb uninstall io.appium.uiautomator2.server.test

如果普通卸载失败，可以尝试：

adb shell pm uninstall io.appium.uiautomator2.server
adb shell pm uninstall io.appium.uiautomator2.server.test

卸载后建议：

1. 重启设备
2. 保持设备亮屏
3. 再重新发起 Session，让 Appium 重新安装

最关键的"真死因"：定位前台服务权限

根据 logcat，典型核心报错类似：

java.lang.SecurityException: Starting FGS with type location ... requires permissions ...

这说明什么

设备系统版本较新（如 Android 14 / 15），而 io.appium.settings 需要启动一个带定位能力的前台服务。

如果它没有获得这些权限，系统会直接强杀：

• ACCESS_FINE_LOCATION
• ACCESS_COARSE_LOCATION
• ACCESS_BACKGROUND_LOCATION
• 某些系统上还会涉及 FOREGROUND_SERVICE_LOCATION

大白话解释

Appium Settings 想启动一个定位相关服务，但系统认为：

1. 它没有足够权限
2. 它不符合后台启动敏感服务的条件

所以直接闪退。

ADB 强制授权

优先执行：

adb shell pm grant io.appium.settings android.permission.ACCESS_FINE_LOCATION
adb shell pm grant io.appium.settings android.permission.ACCESS_COARSE_LOCATION
adb shell pm grant io.appium.settings android.permission.ACCESS_BACKGROUND_LOCATION

必要时还可以尝试：

adb shell pm grant io.appium.settings android.permission.FOREGROUND_SERVICE_LOCATION

说明：

• 如果某条命令提示权限不存在，可以跳过
• ACCESS_BACKGROUND_LOCATION 在 Android 14/15 上通常尤其关键

手动在系统设置中授予定位权限

路径：

• 设置 -> 应用管理 -> Appium Settings -> 权限管理 -> 定位

必须尽量设置为：

• 始终允许

而不是：

• 仅在使用中允许

因为新版 Android 对前台服务的要求更严格。

建议的 Appium Capability

为了降低重复安装和权限问题影响，可考虑加入：

{
  "appium:noReset": true,
  "appium:skipServerInstallation": true,
  "appium:autoGrantPermissions": true
}

含义

• noReset: true
  • 不重置应用状态
• skipServerInstallation: true
  • 如果相关服务已安装，跳过重复安装
• autoGrantPermissions: true
  • 尽量自动授予运行时权限

完美解决

针对 Flutter 应用的额外提醒

如果你测试的是 Flutter 应用，还需要额外确认：

1. 你的业务 App 本身不是因为 Release 包、混淆、权限问题闪退
2. appPackage 与 appActivity 填写准确

可用命令确认当前 Activity：

adb shell dumpsys window | findstr mCurrentFocus

一键排查思路

如果让我把排查流程压缩成一条最实用路径，建议按这个顺序：

1. 开启 USB 安装
2. 盯设备屏幕点击安装确认
3. 开启 Appium Settings 自启动、无限制省电、后台弹窗
4. 手工卸载 Appium 相关包后重装
5. 用 adb 强制授予定位权限
6. 必要时关闭 MIUI 优化
7. 用 adb logcat 抓最终死因