WinScope 编译与使用手册(Android 16)
| 项目 | 验证版本 |
|---|---|
| 主机系统 | Ubuntu 24.04 |
| Node / Python | 24.18 / 3.12 |
| AOSP | Android 16 (25Q2) |
| 设备 | userdebug 版本设备 |
1 编译
1.1 前置条件
- 必须在完整 AOSP 源码树内编译。WinScope 依赖以下目录,单独拷贝
development/tools/winscope无法完成构建:frameworks/base/core/protoexternal/perfettoframeworks/libs/systemui/viewcapturelib
- 工具链:Node 18+,Python 3.10+。
- 建议启用 ccache。无缓存时 WASM 编译约需 20~40 分钟,热缓存时约 1 分钟。
- 磁盘空间:约 3.3 GB。
- 国内网络环境:
- npm 可切换到国内镜像:
npm config set registry https://registry.npmmirror.com install-build-deps需要从 Google 存储下载 emsdk 等依赖。建议在可访问外网的机器上预先准备好external/perfetto/buildtools/,再整体拷贝过来。
- npm 可切换到国内镜像:
1.2 环境变量
后续命令均基于以下变量。<aosp_root> 与 <device_serial> 为占位符,执行前须替换为实际值:
export AOSP=<aosp_root> # AOSP 源码根目录
export WS=$AOSP/development/tools/winscope
export PF=$AOSP/external/perfetto
export DEV=<device_serial> # 通过 adb devices 获取
1.3 构建前清理
# 移开家目录 node_modules,防止 tsc 向上加载 ~/node_modules/@types
[ -d ~/node_modules ] && mv ~/node_modules ~/node_modules.bak
# 源码树被移动或复制过时,清理悬空符号链接(否则报 EEXIST)
for d in ui/out ui/src/gen trace_processor_build/test/data; do
[ -L "$PF/$d" ] && [ ! -e "$PF/$d" ] && rm -f "$PF/$d"
done
1.4 构建步骤
注意:不要直接执行
npm run build:prod,该命令在当前环境下会失败。请按以下步骤分步执行。
# 步骤 1:安装 npm 依赖,生成 proto 解析代码
cd $WS
npm ci --no-audit --no-fund
npm run build:protos
# 步骤 2:安装 perfetto 构建依赖(仅首次执行,约 1.5 GB)
# 末尾 test_data 下载失败可忽略,确认以下文件存在即可:
# buildtools/linux64/emsdk/emscripten/emcc
cd $PF
./tools/install-build-deps --ui
# 步骤 3:编译 WASM(skip_buildtools_check 与 --no-override-gn-args 必须同时使用)
./tools/gn gen --args='is_debug=false cc_wrapper="ccache" skip_buildtools_check=true' trace_processor_build
./ui/node ui/build.js --no-depscheck --no-override-gn-args --out trace_processor_build
# 步骤 4:拷贝 WASM 产物
cd $WS
rm -rf deps_build/trace_processor
mkdir -p deps_build/trace_processor/to_be_served
rsync -ar $PF/trace_processor_build/ deps_build/trace_processor/
cp deps_build/trace_processor/ui/dist_version/engine_bundle.js \
deps_build/trace_processor/wasm/trace_processor.wasm \
deps_build/trace_processor/to_be_served/
# 步骤 5:打包前端(出现 3 条包体积 warning 属正常)
npm run build:app
# 恢复家目录 node_modules
[ -d ~/node_modules.bak ] && mv ~/node_modules.bak ~/node_modules
说明:如果构建中途失败,请手动执行最后一行,恢复
~/node_modules。
1.5 产物校验
cd $WS/dist/prod
ls -lh index.html trace_processor.wasm engine_bundle.js # 约 38.7M / 10M / 245K
head -c 4 trace_processor.wasm | xxd -p # 应输出 0061736d
用浏览器打开 index.html,显示 “Welcome to Winscope” 即表示构建成功。
1.6 常见构建问题
| 现象 | 原因 | 处理 |
|---|---|---|
TS1139,指向 ~/node_modules/@types/d3-* | tsc 向上加载家目录 @types,其中含 TS 5.0 语法,而项目锁定 TS 4.8 | 执行 1.3 节,移开 ~/node_modules |
tsc --noEmit 报 147 个 TS2694 | protobufjs 7.2.5 生成的 .d.ts 存在悬空命名空间 | 不影响构建,可忽略 |
ninja: build stopped / Build deps are stale | GN 中的 check_build_deps 不受 --no-depscheck 控制 | gn 加 skip_buildtools_check=true,build.js 加 --no-override-gn-args |
EEXIST: file already exists, symlink | 源码树迁移后残留悬空链接,existsSync 无法检测到 | 执行 1.3 节清理脚本 |
Cannot find module .../perfetto/build.js | ui/node 是包装脚本,不是目录 | 在 $PF 下执行 ./ui/node ui/build.js |
npm 提示 allowScripts | npm 11 新行为 | 可忽略。若 esbuild / pbjs 缺少二进制,执行 npm approve-scripts --allow-scripts-pending |
2 使用
附上自己编译好的winscope 16 linux工具winscope_linux_16 ,可以直接下载使用。
2.1 部署文件
运行只需以下 4 个文件,打包后约 11 MB:
mkdir -p ~/winscope
cp $WS/dist/prod/{index.html,trace_processor.wasm,engine_bundle.js,winscope_proxy.py} ~/winscope/
注意:
winscope_proxy.py需使用已修复版本,否则 End trace 时会报TimeoutExpired或TypeError。修复内容有两处:
except子句增加subprocess.TimeoutExpired- 删除
self.out = None,末尾的逗号
2.2 设备检查
adb devices -l # 若显示 no permissions:sudo usermod -aG plugdev $USER 后重新登录
adb -s $DEV shell "su root echo ROOT_OK" # 应输出 ROOT_OK
adb -s $DEV shell getprop ro.build.type # 应为 userdebug 或 eng
注意:user 版本无法抓取 WM / SF trace。
2.3 启动代理
cd ~/winscope
nohup python3 winscope_proxy.py > proxy.log 2>&1 &
cat ~/.config/winscope/.token # 获取 token(固定不变)
- 代理监听
localhost:5544,每次收到请求时调用 adb。 - 每台主机只需启动一次,多台设备共用。设备重启或重新插拔无需重启代理。
- 以下情况需要重新启动代理:主机重启、切换用户、代理进程被终止。
- 浏览器与代理不在同一台机器时,在浏览器所在机器上建立端口转发:
ssh -N -L 5544:localhost:5544 <user>@<server>
2.4 网页抓取
- 打开
index.html。直接双击即可;如需图标正常显示,可执行python3 -m http.server 8902 --bind 127.0.0.1后通过浏览器访问。 - 手动粘贴 token,点击 Connect。URL 中的
?token=参数无效。 - 在下拉框中选择设备。未选择设备时,不会显示 Start trace 按钮。
- 在 Trace 标签页勾选 trace 类型:
- 必选:Window Manager、Surface Flinger、Transactions、Screenshot
- 可选:Screen Recording、ProtoLog、Transitions、Input、Wayland
- SF 细项默认只启用 input 和 composition,需手动勾选 hwc 和 trace buffers;多屏场景还需勾选 virtual displays。
- 点击 Start trace,在设备上复现问题,再点击 End trace。屏幕静止时几乎不产生数据。
- 解析完成后,点击 View traces。
2.5 命令行抓取
适用于网页抓取异常或 Windows 环境。仅抓取 WM 与 SF Layers。
# 清理旧数据并配置 SF layer tracing
adb -s $DEV shell "su root rm -f /data/misc/wmtrace/*.winscope"
adb -s $DEV shell "su root service call SurfaceFlinger 1029 i32 32000" # 缓冲区大小
adb -s $DEV shell "su root service call SurfaceFlinger 1033 i32 126" # trace flags(全开)
adb -s $DEV shell "su root service call SurfaceFlinger 1025 i32 1" # 开始 SF tracing
# 配置并启动 WM tracing
adb -s $DEV shell "su root cmd window tracing frame"
adb -s $DEV shell "su root cmd window tracing level verbose"
adb -s $DEV shell "su root cmd window tracing start"
# ---- 在设备上复现问题 ----
# 停止 tracing 并导出
adb -s $DEV shell "su root cmd window tracing stop"
adb -s $DEV shell "su root service call SurfaceFlinger 1025 i32 0" # 停止 SF tracing
sleep 3 # 等待文件写盘
mkdir -p traces
adb -s $DEV pull /data/misc/wmtrace ./traces/
(cd traces/wmtrace && zip ../../traces.zip *.winscope) # 将 traces.zip 拖入 WinScope
注意:不要修改 trace 文件名。WinScope 根据文件名(如
layers_trace、wm_trace)识别 trace 类型。
2.6 分析要点
- SF trace 记录的是状态变化快照,不是逐帧记录。例如 5 秒操作约产生 42 个 entry。
- SF trace 不含像素数据。需要查看实际画面时,请同时抓取 Screenshot 或 Screen Recording。
- 重点属性:
z、bounds、visibleRegion、alpha、crop、transform、buffer、compositionType(CLIENT / DEVICE / SOLID_COLOR)。 - 与 Perfetto 的分工:
| 工具 | 适用问题 |
|---|---|
| WinScope | 层级关系、bounds、花屏、闪烁等合成状态问题 |
| Perfetto | 同一时间点的 SF / HWC 时序、fence、调度 |
2.7 常见问题
| 现象 | 处理 |
|---|---|
| 端口 5544 被占用 | 代理已在运行,直接复用 |
Bad Winscope authorization token | 核对 token;使用 curl 调试时,header 名为 Winscope-Token |
| 设备列表为空或显示 unauthorized | 执行 adb devices -l 检查,并在设备上允许 USB 调试 |
| 时间轴为空或文件为 0 字节 | 抓取期间设备上没有操作 |
| 部分视图为灰色 | 缺少对应 trace 类型,补齐后重新抓取 |
Cannot build frame mapping for IME | 需同时抓取 WM、SF、Transactions、IME |
| Windows 下无法抓取 | 代理依赖 POSIX 环境,改用 2.5 节命令行方式 |