WinScope 编译与使用手册(Android 16)

38 阅读5分钟

WinScope 编译与使用手册(Android 16)

项目验证版本
主机系统Ubuntu 24.04
Node / Python24.18 / 3.12
AOSPAndroid 16 (25Q2)
设备userdebug 版本设备

1 编译

1.1 前置条件

  • 必须在完整 AOSP 源码树内编译。WinScope 依赖以下目录,单独拷贝 development/tools/winscope 无法完成构建:
    • frameworks/base/core/proto
    • external/perfetto
    • frameworks/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/,再整体拷贝过来。

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 个 TS2694protobufjs 7.2.5 生成的 .d.ts 存在悬空命名空间不影响构建,可忽略
ninja: build stopped / Build deps are staleGN 中的 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.jsui/node 是包装脚本,不是目录在 $PF 下执行 ./ui/node ui/build.js
npm 提示 allowScriptsnpm 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 网页抓取

  1. 打开 index.html。直接双击即可;如需图标正常显示,可执行 python3 -m http.server 8902 --bind 127.0.0.1 后通过浏览器访问。
  2. 手动粘贴 token,点击 Connect。URL 中的 ?token= 参数无效。
  3. 在下拉框中选择设备。未选择设备时,不会显示 Start trace 按钮。
  4. 在 Trace 标签页勾选 trace 类型:
    • 必选:Window Manager、Surface Flinger、Transactions、Screenshot
    • 可选:Screen Recording、ProtoLog、Transitions、Input、Wayland
    • SF 细项默认只启用 input 和 composition,需手动勾选 hwc 和 trace buffers;多屏场景还需勾选 virtual displays。
  5. 点击 Start trace,在设备上复现问题,再点击 End trace。屏幕静止时几乎不产生数据。
  6. 解析完成后,点击 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 节命令行方式