|
|
本帖最后由 chenddcoder 于 2026-7-9 18:26 编辑
引言：告别繁琐的 Android UI 调试
在 Android 大屏应用（电视、投影等）开发过程中，UI 调试一直是一个痛点。传统的 LayoutInspector 连接慢、延迟高，uiautomatorviewer 操作繁琐且不支持实时刷新。
@quicktvui/android-inspector 是一款基于 Web 端 的 Android UI 调试工具，通过浏览器即可完成 UI 层级查看、设备信息监控、应用分析、日志检索等一系列操作，无需安装 Android Studio，即装即用。
安装与启动环境要求- Node.js >= 16
- ADB 环境已配置（adb devices 可正常识别设备）
- Android 设备已开启 USB 调试
安装npm install -g @quicktvui/android-inspector
启动android-inspector启
动后会自动打开浏览器，访问 http://localhost:3001 即可看到调试界面。
如果 3001 端口被占用，会自动尝试 3002、3003... 直到找到可用端口。
初次启动界面如下，在设备列表中选择已连接的设备即可开始调试。
核心功能
1. 设备连接与管理支持 USB 连接和远程 ADB 连接两种方式：
- USB 连接：插上设备，执行 adb devices 确认连接后，界面自动识别
- 远程连接：在界面中输入设备的 IP 地址，通过 /api/connect 接口执行 adb connect
设备列表会展示所有已连接的设备 ID，选择后可切换调试目标。
2. UI 层级检视（核心）这是工具的核心功能。采用 双引擎 模式获取 UI 层级：
| 引擎 | 数据来源 | 优势 | 劣势 | | UIAutomator | uiautomator dump | 坐标绝对精准，包含 text/content-desc | TV 上首次调用可能失败（自动重试 3 次） | | Dumpsys | dumpsys activity top | 真实的 ClassName，支持 View Hierarchy 解析 | 坐标为相对值，需计算绝对位置 |
双引擎合并渲染：前端将两棵树交叉遍历，UIAutomator 提供精确坐标和文本，Dumpsys 提供真实类名，开发者可以在界面上同时看到两者的综合信息。
支持的 UI 节点属性- class — 视图类名（如 android.widget.TextView）
- id — resource-id
- text / content-desc — 文本内容
- bounds — 坐标与宽高
- focused / focusable — 焦点状态（TV 开发中非常关键！）
- enabled / clickable / selected — 交互状态
- visibility — 可见性（VISIBLE / INVISIBLE / GONE）
3. 设备信息面板分为 静态信息（仅首次获取，缓存复用）和 动态信息（实时刷新）：
静态信息（一次性采集）
{ "device": { "model": "...", "manufacturer": "...", "androidVersion": "14", "sdkLevel": 34 }, "cpu": { "cores": 8, "architecture": "arm64-v8a" }, "memory": { "totalKB": 4194304 }, "display": { "resolution": "1920x1080", "dpi": 320, "refreshRate": 60 }, "storage": { "total": "...", "used": "...", "free": "..." }, "app": { "packageName": "...", "pid": 1234, "topActivity": "..." }}
动态监控指标（支持独立开关，按需采集）
| 指标 | 数据来源 | 说明 | | CPU 使用率 | /proc/stat | 每核独立采集 + 平均值，增量计算 | | 内存使用 | /proc/meminfo + dumpsys meminfo | 可用内存、App PSS/Java Heap/Native Heap | | 网络流量 | /proc/net/dev | 各接口收发字节数 + 增量 | | 线程统计 | /proc/[pid]/status + ps -A | App 线程数 + 系统进程总数 | | GPU 渲染 | dumpsys gfxinfo | 帧耗时、Jank 数、FPS、90/95/99 分位 | | 编解码器 | dumpsys media.codec | 活跃编解码器信息 | | 电池/温控 | dumpsys battery + dumpsys thermalservice | 电量、温度、充电状态、各传感器温度 |
4. 应用分析针对当前前台应用（或指定包名），提供深度分析：
静态分析（一次采集，缓存复用）
- 包信息：版本名、版本号、targetSdk、minSdk、安装/更新时间
- 签名信息：自动识别 debug 签名
- 权限列表：已授予 vs 已请求，一目了然
- 组件统计：Activity / Service / Receiver / Provider 数量及类名，自动识别主 Activity
动态分析（实时采集）
- 进程状态：所有关联进程 PID、运行时长、文件描述符数
- Activity 栈：当前应用在 Task 中的 Activity 历史栈
- 运行中的 Services：进程、PID、创建时间、崩溃次数、重启次数、绑定数
- 内存分布：每个进程的 Java Heap / Native Heap / Code / Stack / Graphics 详细分布
- 网络统计：通过 UID 过滤应用网络流量
- 活跃通知数
5. Logcat 日志查看器支持丰富的过滤功能，告别在终端中 grep 的痛苦：
- Tag 过滤（支持多个 Tag 或的关系）
- Level 过滤（V/D/I/W/E/F，>= 级别）
- 包名过滤（自动解析 PID，精确匹配进程）
- 排除 Tag（过滤掉噪声日志）
- 实时查看 vs 历史回溯
6. 日志导出一键导出设备关键诊断日志：
| 来源 | 内容 | | Logcat Main | 应用日志主缓冲区 | | Logcat System | 系统服务日志 | | Logcat Crash | 崩溃日志 | | Logcat Events | 事件日志（Activity、输入、电池等） | | Logcat Kernel | 内核日志 (dmesg) | | ANR Traces | /data/anr/ 下的 ANR 堆栈 | | Tombstones | /data/tombstones/ 下的 Native Crash 堆栈 | | DropBox | /data/system/dropbox/ 系统错误记录 |
所有日志打包为 zip，方便分享给团队成员。
7. 屏幕截图通过 adb exec-out screencap -p 流式获取设备截图，直接在浏览器中查看当前设备画面。
8. Activity 栈查看解析 dumpsys activity activities，以 Task 为单位展示所有 Activity 栈，支持前台 Activity 高亮。
实战技巧大屏/TV 开发调试电视设备通常没有 USB 调试的便利性，远程连接 功能非常实用：
- 确保电视和电脑在同一网络
- 电视端开启 ADB 调试
- 在工具界面输入电视 IP，点击连接
- 开始调试
处理 UIAutomator 超时TV 设备上 uiautomator dump 首次调用经常失败，这是因为 UIAutomator 服务首次启动需要时间。工具已内置 3 次自动重试 机制，通常一次即可成功。
获取真实 ClassNameuiautomator dump 返回的 class 有时会是泛化类型（如 android.view.View），如果需要获取真正的视图类名（如 com.example.MyCustomView），请查看 Dumpsys 模式下的 View Hierarchy。
日志定位问题在 TV 上调试时，建议：
- 按包名过滤（自动解析 PID，只显示目标应用的日志）
- 按 Level >= W 过滤（只看警告和错误）
- 排除系统 Tag（如 WindowManager, InputReader 等噪声）
与其他工具对比[td]| 特性 | android-inspector | LayoutInspector | uiautomatorviewer | | 安装方式 | npm 全局安装 | Android Studio 自带 | Android SDK 自带 | | 启动速度 | 秒级 | 慢（需等待进程选择） | 中等 | | 实时刷新 | ✅ WebSocket 轮询 | ✅ Live Update（高延迟） | ❌ 手动刷新 | | 远程设备 | ✅ ADB over IP | ❌ | ❌ | | 远程使用 | ✅ Web 界面，可分享 | ❌ 本地 IDE | ❌ 本地工具 | | 设备监控 | ✅ CPU/内存/网络/GPU | ❌ | ❌ | | 应用分析 | ✅ 深度分析 | ❌ | ❌ | | 日志查看 | ✅ 内置 Logcat 查看器 | ❌ | ❌ | | TV 适配 | ✅ 针对 TV 优化重试 | ❌ 经常连接超时 | ❌ 不支持 | | 跨平台 | ✅ Web 界面 | ❌ 仅 IDE | ❌ 仅桌面工具 |
项目地址
开发总结@quicktvui/android-inspector 作为 QuickTVUI 生态中的调试利器，完美解决了大屏 Android 应用开发中的 UI 调试痛点：
- 零安装 IDE — npm 全局安装即可使用，无需打开 Android Studio
- Web 界面 — 可在浏览器中直接使用，支持远程分享
- 双引擎 UI 检视 — UIAutomator 精确坐标 + Dumpsys 真实类名，互相补充
- 全方位设备监控 — CPU、内存、网络、GPU 渲染、电池温度一站式查看
- 深度应用分析 — 从包信息到进程、Service、Activity 栈，无所不包
- 强大的日志系统 — 多维度过滤、多源导出，问题定位效率翻倍
对于 QuickTVUI 快应用开发者和 Android TV 开发者来说，android-inspector 是不可或缺的调试工具，强烈推荐！
|
|
发表于