3. 环境准备与工具链：Android SDK、adb、UiAutomator、dumpsys gfxinfo、systrace/perfetto的安装与配置

3.1 现象识别：工具链缺失的典型表现

TalkBack 渲染延迟分析依赖一套完整的本地工具链。任何一个环节缺失或版本错配，都会在数据采集阶段暴露为“哑炮”现象——命令无输出、设备离线、Trace 文件为空或自动化测试直接崩溃。下表中列出了最常见的工具链故障现象与根因对应关系。

3.2 数据采集：工具链安装与配置

本节按照“底层 SDK → 通信桥梁 → 专项工具”的层次，逐一完成安装与验证。下方的工具链架构图概括了各组件之间的数据流和配置要点，可作为全流程的视觉索引。

3.2.1 Android SDK 安装与环境变量

1. 下载命令行工具： 从 Android 开发者网站 获取 commandlinetools 压缩包，解压至 ~/Android/Sdk。
2. 安装平台与构建工具：

cd ~/Android/Sdk/cmdline-tools/latest/bin
./sdkmanager --list | grep -E "platforms;android-|build-tools;"
./sdkmanager "platforms;android-34"
./sdkmanager "build-tools;34.0.0"
./sdkmanager "platform-tools"

1. 配置环境变量（~/.bashrc 或 ~/.zshrc）：

export ANDROID_HOME="$HOME/Android/Sdk"
export PATH="$PATH:$ANDROID_HOME/platform-tools"
export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin"

1. 重载并验证：

source ~/.bashrc
echo $ANDROID_HOME
adb version

3.2.2 ADB 与设备连接

• 驱动（Windows）： 安装 Google USB Driver，设备管理器更新驱动为 Android Composite ADB Interface。
• 启用开发者选项： 设备上连续点击“版本号”7 次 → 开启“USB 调试”。
• 验证连接：

adb kill-server
adb start-server
adb devices
# 预期输出：List of devices attached
#           0123456789ABCDEF    device

3.2.3 UiAutomator 依赖配置

在 App 的 build.gradle (模块级) 中添加依赖：

androidTestImplementation 'androidx.test.uiautomator:uiautomator:2.3.0'
androidTestImplementation 'androidx.test:runner:1.6.1'
androidTestImplementation 'androidx.test:rules:1.6.1'

在 AndroidManifest.xml 中添加：

<uses-library android:name="android.test.runner" />

3.2.4 dumpsys gfxinfo 基础验证

安装完成后，直接执行以下命令检查是否可获取帧数据：

adb shell dumpsys gfxinfo com.android.talkbreak  # 替换为目标包名
# 如果输出包含 "Stats since:" 或 "Profile data in ms:" 则表示工具可用
# 若输出 "No samples" 说明还没有渲染帧被记录，属于正常状态

3.2.5 Systrace / Perfetto 安装与配置

Systrace（API 级别 ≤ 29 推荐）：

# 通过 SDK 管理器安装 platform-tools 后，systrace 位于 SDK 根目录
python2 $ANDROID_HOME/platform-tools/systrace/systrace.py \
  --time=10 -o trace.html gfx input view res

Perfetto（API 级别 ≥ 30 推荐）：

# 1. 设备端启用 Perfetto 服务（Android 12+ 默认开启）
adb shell perfetto --version

# 2. 抓取 10 秒渲染相关 trace
adb shell perfetto \
  -c - --txt \
  -o /data/misc/perfetto-traces/trace.perfetto-trace <<< '
buffers: {
    size_kb: 10240
}
data_sources: [
    { config { name: "gpu.memory" } },
    { config { name: "linux.ftrace" } },
    { config { name: "android.surfaceflinger" } }
]
duration_ms: 10000
'

# 3. 拉取到主机
adb pull /data/misc/perfetto-traces/trace.perfetto-trace ./trace.perfetto-trace

3.3 原因定位：工具链配置诊断

当验证命令返回错误时，按以下故障树逐层排查：

1. ADB 设备离线： adb kill-server → adb start-server → 重新插拔 USB → 检查设备“USB 调试”是否仍开启。
2. dumpsys 命令报 not found： 确认 platform-tools 版本 ≥ 30；确认 adb shell 可进入；检查 adb shell dumpsys 是否列出全部服务。
3. Perfetto Trace 为空： 检查 /data/misc/perfetto-traces/ 目录是否存在、可写；使用 adb shell perfetto --query 查看已启用数据源。
4. UiAutomator 测试无法运行： 确认 androidTestImplementation 作用域、确认测试设备 API 级别 ≥ 18；检查 AndroidManifest.xml 中 uses-library 的 android:required="false" 属性。

3.4 修复动作：常见问题解决方案

3.5 复测验证：工具链正确性检查

依次执行以下五项验证，全部通过即代表环境就绪：

1. SDK 路径： echo $ANDROID_HOME → 输出非空且指向正确目录。
2. ADB 连接： adb devices → 设备状态为 device。
3. dumpsys 可执行： adb shell dumpsys gfxinfo → 不返回 not found。
4. Perfetto 可执行： adb shell perfetto --version → 返回版本号。
5. UiAutomator 编译： ./gradlew assembleAndroidTest → BUILD SUCCESSFUL。

#!/bin/bash
echo "=== 1. ANDROID_HOME ===" ; echo $ANDROID_HOME
echo "=== 2. ADB ===" ; adb devices | grep -E "device$"
echo "=== 3. dumpsys ===" ; adb shell dumpsys gfxinfo | head -3
echo "=== 4. Perfetto ===" ; adb shell perfetto --version
echo "=== 5. 编译 ===" ; ./gradlew assembleAndroidTest 2>&1 | tail -3

3.6 预防方案：工具链维护最佳实践

• 版本锁定： 在项目根目录的 local.properties 中固定 SDK 路径，避免多项目冲突。
• 自动化检测 CI： 在 CI 流水线中嵌入 check_toolchain.sh，环境不符时提前中断。
• 定期升级： 每月执行 sdkmanager --update，保持 platform-tools 和 build-tools 为最新稳定版。
• Perfetto 持续化： 在设备上启用 adb shell setprop persist.traced.enable 1，避免每次重启后重新配置。
• 文档化： 在团队的 Onboarding Wiki 中维护一份“工具链版本对照表”，明确记录每个 TalkBack 版本所需的最低 SDK/ADB/Perfetto 版本。