Android ADB 调试技能#

概述#

此技能通过调用系统环境变量中的 adb 命令操作 Android 设备。执行任何 ADB 操作前，必须先执行「设备检测流程」。

---

编码完成后的验证流程#

每当完成 Android 端代码修改（包括 Flutter Android、原生 Android 等），必须在回复末尾主动附上以下提示：

📱 代码已修改，建议通过 ADB 验证效果：

1. 构建 APK： flutter build apk --debug / ./gradlew assembleDebug
2. 检测设备并安装：（执行设备检测流程 → 自动安装）
3. 查看运行日志： adb logcat --pid=$(adb shell pidof <包名>)

需要我帮你执行安装和日志监控吗？

不要等用户主动询问，编码任务完成即触发此提示。

---

核心流程：设备检测#

每次执行 ADB 操作前必须先运行设备检测。

bash

# 检测 adb 是否可用
which adb || echo "ADB_NOT_FOUND"

# 获取已连接设备列表
adb devices

设备数量判断逻辑#

情况处理方式adb 命令不存在提示用户安装 Android SDK Platform Tools，并给出下载地址0 台设备提示用户连接设备或开启 USB 调试，给出排查步骤1 台设备直接执行，无需用户确认多台设备展示设备列表，让用户选择目标设备，所有后续命令加 -s <serial> 参数

设备列表展示格式（多设备时）#

text

检测到 N 台已连接的 Android 设备：

序号  设备序列号           状态    设备信息
 1   emulator-5554        online  [模拟器]
 2   R3CT90BFXXX         online  [获取型号]
 3   192.168.1.100:5555   online  [无线连接]

请输入序号选择目标设备：

获取设备型号：

bash

adb -s <serial> shell getprop ro.product.model

---

功能模块#

1. 安装 APK#

bash

# 单设备
adb install -r <apk_path>

# 指定设备
adb -s <serial> install -r <apk_path>

# 常用参数说明：
# -r  允许覆盖安装（保留数据）
# -d  允许降级安装
# -g  自动授予所有运行时权限（Android 6.0+）
# -t  允许安装测试 APK

安装结果判断：

• Success → 安装成功，显示包名
• INSTALL_FAILED_* → 解析错误码并给出中文说明和解决方案

常见错误码对照表见 references/install-errors.md

---

2. 抓取 Logcat 日志#

bash

# 清除旧日志
adb [-s <serial>] logcat -c

# 按包名过滤（需先获取 PID）
PID=$(adb [-s <serial>] shell pidof <package_name>)
adb [-s <serial>] logcat --pid=$PID

# 按 Tag 过滤
adb [-s <serial>] logcat -s <TAG>:V

# 按级别过滤（V/D/I/W/E/F）
adb [-s <serial>] logcat *:E

# 保存到文件
adb [-s <serial>] logcat --pid=$PID > logcat_$(date +%Y%m%d_%H%M%S).log

# 实时过滤关键词
adb [-s <serial>] logcat | grep <keyword>

用户输入包名时的标准流程：

1. 先用 pidof 获取 PID
2. 若 PID 为空（应用未运行），提示用户先启动应用，或改用包名关键词 grep
3. 提供实时输出与保存文件两个选项

---

3. 查看已安装应用列表#

bash

# 所有应用
adb [-s <serial>] shell pm list packages

# 只看第三方应用（用户安装的）
adb [-s <serial>] shell pm list packages -3

# 只看系统应用
adb [-s <serial>] shell pm list packages -s

# 包含 APK 路径
adb [-s <serial>] shell pm list packages -f

# 搜索关键词（如 "wechat"）
adb [-s <serial>] shell pm list packages | grep <keyword>

# 获取应用详细信息
adb [-s <serial>] shell dumpsys package <package_name>

输出格式化：去掉 package: 前缀，每行一个包名，按字母排序后展示。

---

4. 卸载应用#

bash

# 卸载（保留数据）
adb [-s <serial>] shell pm uninstall -k <package_name>

# 完全卸载
adb [-s <serial>] uninstall <package_name>

---

5. 清除应用数据#

bash

adb [-s <serial>] shell pm clear <package_name>

---

6. 启动/停止应用#

bash

# 启动应用（需要知道 MainActivity）
adb [-s <serial>] shell monkey -p <package_name> -c android.intent.category.LAUNCHER 1

# 强制停止
adb [-s <serial>] shell am force-stop <package_name>

# 启动指定 Activity
adb [-s <serial>] shell am start -n <package_name>/<activity_name>

---

7. 截图与录屏#

bash

# 截图并拉取到本地
adb [-s <serial>] shell screencap /sdcard/screenshot.png
adb [-s <serial>] pull /sdcard/screenshot.png ./screenshot_$(date +%Y%m%d_%H%M%S).png

# 录屏（最长3分钟，Ctrl+C 停止）
adb [-s <serial>] shell screenrecord /sdcard/record.mp4
adb [-s <serial>] pull /sdcard/record.mp4 ./record_$(date +%Y%m%d_%H%M%S).mp4

---

8. 文件操作#

bash

# 推送文件到设备
adb [-s <serial>] push <local_path> <device_path>

# 从设备拉取文件
adb [-s <serial>] pull <device_path> <local_path>

---

9. 设备信息查询#

bash

# 设备型号
adb [-s <serial>] shell getprop ro.product.model

# Android 版本
adb [-s <serial>] shell getprop ro.build.version.release

# API Level
adb [-s <serial>] shell getprop ro.build.version.sdk

# 电池信息
adb [-s <serial>] shell dumpsys battery

# CPU 信息
adb [-s <serial>] shell cat /proc/cpuinfo

# 内存信息
adb [-s <serial>] shell cat /proc/meminfo

# 应用内存占用
adb [-s <serial>] shell dumpsys meminfo <package_name>

# 设备 IP 地址
adb [-s <serial>] shell ip addr show wlan0

---

10. 无线 ADB 连接#

bash

# USB 连接后，开启 TCP 模式（Android 11 以下）
adb [-s <serial>] tcpip 5555
adb connect <device_ip>:5555

# Android 11+ 无线配对（设置 → 开发者选项 → 无线调试）
adb pair <ip>:<port>   # 输入配对码
adb connect <ip>:5555

---

11. 重启设备#

bash

# 正常重启
adb [-s <serial>] reboot

# 重启到 Recovery
adb [-s <serial>] reboot recovery

# 重启到 Bootloader
adb [-s <serial>] reboot bootloader

---

输出规范#

1. 始终显示实际执行的命令，让用户知道运行了什么
2. 命令输出用代码块包裹，保持原始格式
3. 中文解释结果，不要让用户自己看英文错误
4. 多步骤操作 给出进度提示（如"正在安装... 安装完成 ✓"）
5. 失败时 给出具体原因和解决步骤，不只是报错

---

ADB 环境排查#

若 adb 命令找不到：

bash

# macOS / Linux 检查
echo $ANDROID_HOME
ls $ANDROID_HOME/platform-tools/adb

# Windows 检查
echo %ANDROID_HOME%
where adb

下载地址： https://developer.android.com/studio/releases/platform-tools

PATH 配置（以 macOS/Linux 为例）：

bash

export ANDROID_HOME=$HOME/Library/Android/sdk   # macOS
export PATH=$PATH:$ANDROID_HOME/platform-tools