3. 数据采集前置条件：调试模式、系统权限、抓取时长、符号化配置
在正式开始 Profiler 抓取卡顿堆栈之前，必须确认四个关键前置条件。任何一个条件不满足，都可能造成采集数据无效或误导后续定位。
| 前置条件 | 要求值 | 验证方式 | 常见问题 |
|---|---|---|---|
| 调试模式 | Debuggable = true / Release 包需手动开启 profileable | adb shell dumpsys package <包名> | grep flags | Release 包未加 profileable=true 导致 Profiler 无法附加进程 |
| 系统权限 | Root 或 adb 授权（track 系统级卡顿需 root） | adb shell whoami | 普通 App 无权限读取系统帧数据（SurfaceFlinger / Choreographer） |
| 抓取时长 | 10～30 秒（持续卡顿）或 60～120 秒（偶现卡顿） | Profiler 时间轴显示 | 抓取不足 5 秒样本过少；超过 120 秒可能触发锁帧降频 |
| 符号化配置 | 需映射文件/符号表（.so symbols, ProGuard mapping） | 检查 Profiler 符号下载路径 | 未配置符号表导致堆栈地址不可读 |
✅ 最佳实践：在“现象识别”阶段（上一章）已经确认卡顿可复现后，立即执行以下三步检查：① 确认 apk 为 debug 或 profileable；② 连接 USB 并授权 adb root（若需）；③ 预先下载对应构建版本的符号表，并配置到 Profiler 工具路径中。
3.1 调试模式：不只是 Debug 包
Android 10+ 支持 profileable 属性，Release 包也能被 Profiler 附加。配置方式：
# 在 AndroidManifest.xml 的 <application> 标签内添加
android:profileable="true"
# 或通过 Gradle 构建时注入：
android {
defaultConfig {
// 仅在 profiling 版本添加
}
}验证调试模式：
adb shell dumpsys package com.example.app | grep -E "flags|profileable"
⚠️ 常见坑：部分低版本 Profiler 不识别 profileable 属性，此时必须使用 debug 包。如遇 Profiler 无法 attach，先降级到 debug 构建。
3.2 系统权限：Root vs 非 Root
- 非 Root 设备：只能获取本进程 Java 堆栈，无法获取系统帧率、SurfaceFlinger 数据。适合定位纯应用层卡顿。
- Root 设备：可查看 Choreographer 回调、GPU 渲染时间、系统 Binder 调用。适合解决输入响应、列表滑动帧丢失问题。
临时授权（无需 root）示例：
adb shell
# 如果 adb 有 root 权限（需刷入 su）
su
# 或者使用 Android 10+ 的 cmd 命令（部分厂商开放）
adb shell cmd activity manager set-profiler-debug com.example.app system/everyone3.3 抓取时长：多短算短，多长算长
核心原则：抓取时长应至少包含 3～5 次完整卡顿周期。对于连续卡顿，10 秒足够；对于偶现卡顿（如每 30 秒出现一次），建议抓取 120 秒。
| 卡顿类型 | 推荐抓取时长 | 采样频率 |
|---|---|---|
| 连续微弱卡顿（丢帧 ≤5 帧） | 10 秒 | 每帧采样（16.6ms） |
| 间断严重卡顿（丢帧 20+ 帧） | 60 秒 | 每 50ms 采样一次 |
| 页面切换卡顿 | 30 秒（包含切换前后各 10 秒） | 手动标记切换时刻 |
3.4 符号化配置：从地址到方法名
Profiler 输出的原始堆栈为虚拟地址，需要符号化才能解析为函数名。配置步骤：
- native 层：获取 .so 的 unstripped 版本，或保留 DWARF 调试信息。符号表路径必须与构建时对应。
- Java / Kotlin 层：如果使用 ProGuard / R8，需要保留 mapping.txt 文件。
- Profiler 符号设置：在 Android Studio Profiler → Settings → Symbol Directories 中添加目录。
# 示例：手动符号化一条 Stack Trace
# 使用 ndk-stack 解析 so 地址
ndk-stack -sym /path/to/obj/local/armeabi-v7a -dump crash.txt
💡 技巧：可以在 CI/CD 流程中自动打包符号文件，与 APK 同版本号归档。Profiler 支持直接在设备端加载符号包，无需每次都下载到本地。
完成以上四个条件后，即可进入正式的数据采集流程。采集过程中还应持续观察 Profiler 状态面板，确保无采样丢失、符号缺失的警告。