简介：这份资源是 Android SDK 平台工具 r31.0.3 的 Windows 版 Systrace 组件压缩包，面向需要做系统级性能分析与卡顿排查的 Android 开发者，尤其适合已具备一定调试基础、希望深入理解应用运行时行为的中高级工程师。包内共 1712 个文件，以 html 报告模板与文档、py 脚本（含 systrace.py 主程序及各类测试脚本）、md 说明、js 与 css 前端资源为主，另有 exe 可执行文件、json 配置及 atrace 采集样例数据等，压缩包约 9.98MB，目录结构完整，便于按模块查阅。已有 875 人学习下载。借助其中的命令行工具，读者可按类别采集 CPU 调度、图形渲染、输入处理等事件，生成可视化时间线 HTML 报告，并结合样例数据理解采集流程与结果解读，为定位卡顿、延迟等性能问题提供可复用的分析手段。
1. 从一次抓不到 trace 的翻车说起：platform-tools r31.0.3 到底装的是什么
上周帮同事排查一个滑动卡顿问题，他信誓旦旦说 systrace 已经跑起来了，结果抓出来的 html 打开一片空白，命令行里只有一行Unable to find trace file。折腾半小时才发现，他机器上装的是三年前某个 IDE 自带的 adb，版本停在 28.x，systrace 脚本压根没跟着 platform-tools 一起更新。这种坑在环境搭建阶段特别常见——大家以为adb devices能认出手机就算装好了，实际上 platform-tools 是一整包工具集，adb、fastboot、systrace、etc1tool 都在里面，版本对不上，systrace 就是抓不出东西。
这篇记录围绕platform-tools_r31.0.3-windows-systrace.rar这个包展开，讲清楚在 Windows 上怎么把它装干净、环境变量怎么配、systrace 怎么跑通、装坏了怎么回退。适合两类人：一是第一次接触 systrace、想抓系统级性能数据的开发者；二是机器上已经有一堆旧版 adb、想统一到 r31.0.3 这个版本的熟手。r31.0.3 属于 platform-tools 31.x 系列，systrace 脚本仍然是 Python 实现，对 Python 版本有要求，这点后面会单独说。
2. 装前把环境列清楚：r31.0.3 的版本选择与依赖核对
2.1 为什么锁定 r31.0.3 而不是随手拿最新包
platform-tools 的版本号跟 Android 平台版本不是一一对应的，31.x 是一个相对稳定的分支，adb 协议、fastboot 命令集在这个分支上变动不大。选 r31.0.3 的理由很实际：它自带的 systrace 脚本兼容 Python 3.6 以上，同时保留了--from-file这类离线分析参数，抓完的 trace 可以脱离设备二次处理。再新的 33.x、34.x 分支在 Windows 上对旧设备的兼容性反而有波动，尤其是某些厂商定制机，adb 握手阶段容易超时。我一般建议团队统一到一个验证过的版本，r31.0.3 就是这样一个"够用且稳"的锚点。
需要提醒的是，这个包是 rar 压缩格式，解压后是一个platform-tools目录，里面没有安装程序，纯绿色。所以"安装"的本质是解压到固定路径 + 配环境变量，不存在注册表写入，卸载也就是删目录 + 清变量，这点对运维很友好。
2.2 依赖清单：Python、驱动、USB 调试三件事
systrace 能不能跑，取决于三样东西是否到位，缺一个都会在运行时报错，而且报错信息往往不指向根因。
| 依赖项 | 要求 | 缺失时的典型现象 |
|---|---|---|
| Python | 3.6 及以上，需在 PATH 中 | systrace报python is not recognized |
| 设备驱动 | 厂商 USB 驱动或通用 ADB 驱动 | adb devices显示unauthorized或空列表 |
| USB 调试 | 设备开发者选项中开启 | adb devices完全无输出 |
| 解压工具 | 支持 rar（如 7-Zip） | 解压报错或文件损坏 |
Python 这块有个细节：Windows 上如果同时装了 Microsoft Store 版 Python 和官网安装包版，where python可能指向 Store 的别名，systrace 调用时会弹应用商店。我一般会先跑where python确认路径，指向WindowsApps的就说明踩了这个坑，需要调整 PATH 顺序或改用py -3启动器。
2.3 解压路径的选择：别放在带空格和中文的目录
解压目标路径建议固定为C:\Android\platform-tools，不要放在C:\Program Files或桌面、下载目录。原因有两个：一是路径带空格时，某些脚本拼接命令会断词；二是中文路径在 systrace 生成输出文件时可能编码异常。我见过把工具解压到D:\工具\安卓\platform-tools的，adb 能用，但 systrace 输出 html 时文件名乱码，排查了半天。
解压后目录里应该能看到这些关键文件：adb.exe、fastboot.exe、systrace\systrace.py、etc1tool.exe、dmtracedump.exe。如果systrace目录不存在，说明包不完整或者解压工具没处理好 rar 内的子目录，需要重新解压。
3. 安装与配置：从解压到环境变量一次配到位
3.1 解压并校验文件完整性
用 7-Zip 右键解压到C:\Android，得到C:\Android\platform-tools。解压完先做一次文件校验，确认关键可执行文件和脚本都在。
# 进入解压后的目录，列出关键文件 cd /d C:\Android\platform-tools dir adb.exe fastboot.exe systrace\systrace.py这段命令在 cmd 下执行，dir后面跟多个文件名会逐个检查是否存在。三个文件都列出来才算解压完整。如果systrace\systrace.py报"找不到文件"，多半是解压时只解了顶层目录，rar 里的子目录被跳过，换 7-Zip 的"解压到当前文件夹"再试一次。校验通过后，先别急着配环境变量，直接在目录里跑一次adb version，确认二进制本身能启动。
# 在 platform-tools 目录内直接运行，验证二进制可用 adb version正常输出类似Android Debug Bridge version 1.0.41，版本号对应 r31.0.3 这一批。如果提示"不是内部或外部命令"，说明当前目录不对或者文件被杀毒软件隔离了，后者在 Windows Defender 上偶有发生，需要把目录加入排除项。
3.2 配置 PATH：用户变量还是系统变量
环境变量这一步是翻车高发区。常见做法是加到"系统变量"的 Path 里，但如果你不是管理员，或者公司机器有策略限制，改系统变量会失败。我一般优先改"用户变量"，只影响当前账户，够用且不需要提权。
操作路径：Win + R 输入sysdm.cpl→ 高级 → 环境变量 → 在"用户变量"里选中 Path → 编辑 → 新建 → 填入C:\Android\platform-tools→ 一路确定。注意是填目录本身，不要填到adb.exe，也不要带结尾反斜杠。
配完后必须新开一个 cmd 窗口验证，老窗口的环境变量是启动时快照的，不会自动刷新。
# 新开 cmd 窗口，确认 PATH 生效 where adb where pythonwhere adb应该只输出一行C:\Android\platform-tools\adb.exe。如果输出多行，说明机器上还有别的 adb（比如某个 IDE 自带的），PATH 顺序决定了哪个优先。多版本共存时，把C:\Android\platform-tools上移到最前面，避免旧版 adb 抢占。where python同理，确认指向真实安装路径而非 Store 别名。
3.3 systrace 脚本的调用方式与参数取舍
systrace 不是一个独立 exe，而是systrace\systrace.py这个 Python 脚本。r31.0.3 里它支持直接python systrace.py调用，也支持通过systrace目录下的批处理间接调用。我习惯显式用 Python 调，参数看得清楚。
# 抓取 5 秒的 sched、gfx、view 三类 trace，输出到当前目录 python C:\Android\platform-tools\systrace\systrace.py -t 5 sched gfx view -o trace.html参数说明：-t 5是抓取时长，单位秒，太短抓不到完整交互，太长文件巨大，一般 5 到 10 秒够用；sched gfx view是要采集的 category，sched 看调度、gfx 看渲染、view 看视图层级，按排查目标增减；-o指定输出文件名，不指定会生成默认名。还有几个常用参数值得记住：-a指定应用包名，只抓某个 App 的 trace；--from-file用于离线分析已有 trace；-l列出当前设备支持的所有 category，不确定抓什么时先跑这个。
提示：
-l列出的 category 因设备而异，厂商定制系统可能裁剪了部分 category，抓取时报"category not found"不是脚本坏了，是设备不支持。
3.4 设备连接与授权的一次性处理
systrace 依赖 adb 与设备通信，所以设备必须先被 adb 认出来。插上 USB 后跑adb devices，第一次连接会在手机上弹授权框，勾选"始终允许"再确定。如果没弹框，检查开发者选项里的"USB 调试"是否真的打开，有些机型还需要额外打开"USB 安装"或关闭"仅充电"模式。
# 查看设备状态，device 才算就绪 adb devices adb kill-server adb start-serveradb devices输出device表示就绪，unauthorized表示授权没通过，offline表示连接异常。后两种先跑adb kill-server再adb start-server重启服务，多数情况能恢复。还不行就换根数据线——血泪经验，劣质线只能充电不能传数据，表现就是设备列表一直空。
4. 避坑与排查：systrace 跑不起来的五类现场
4.1 现象：报 python 不是内部或外部命令
原因通常是 Python 没装、没进 PATH，或者 PATH 里指向了 Store 别名。解决分两步：先where python看指向，指向WindowsApps就去"应用执行别名"里关掉 python 的别名；完全没有输出就装一个 Python 3.8 以上的版本，安装时勾选"Add Python to PATH"。装完重开 cmd 再验证。
4.2 现象：trace.html 打开是空白或只有时间轴没有数据
原因多半是 category 选错或设备不支持所选 category。先用python systrace.py -l列出设备支持的 category，从里面挑。另一个可能是抓取时长内没有任何交互，系统处于空闲，trace 里自然没内容，抓的时候手动滑一下界面。还有一种少见情况：输出文件被浏览器缓存了旧版本，换个文件名或强制刷新。
4.3 现象：adb devices 显示 unauthorized 反复弹框
原因是设备端的授权密钥与主机不匹配，常见于换了电脑或重装系统后。解决：手机上进入开发者选项，点"撤销 USB 调试授权"，拔插数据线重新授权。如果还不行，删掉主机上的%USERPROFILE%\.android\adbkey和adbkey.pub，重启 adb 服务重新生成密钥对。
4.4 现象：多版本 adb 冲突，命令行为诡异
机器上同时存在 IDE 自带 adb 和 r31.0.3 时，adb devices可能一会儿能认一会儿不能。原因是两个 adb server 版本不一致，互相踢服务。解决：where adb找出所有副本，把不需要的从 PATH 移除或改名，统一用 r31.0.3。我一般会在团队里约定只保留一份 platform-tools，IDE 里的 adb 指向同一路径。
4.5 现象：解压后 systrace 目录缺失或脚本报语法错误
前者是 rar 解压不完整，换 7-Zip 重解。后者多半是 Python 版本过低，r31.0.3 的 systrace 脚本用了 f-string 等 3.6+ 语法，Python 2.7 或 3.5 会直接语法报错。python --version确认版本，低于 3.6 就升级。升级后如果还有报错，检查脚本是否被编辑器改过编码，UTF-8 无 BOM 是安全选择。
5. 装完怎么验证跑通：三步确认法与一个离线分析技巧
验证不能只看adb version有输出就完事，那只能证明二进制没坏。我习惯走三步：工具链自检、设备连通、trace 产出可用。
第一步，工具链自检。新开 cmd，依次跑adb version、fastboot --version、python --version，三个都有正常输出，说明 PATH 和依赖到位。fastboot 容易被忽略，但它和 adb 同包，能跑起来说明整个 platform-tools 目录结构完整。
第二步，设备连通。adb devices输出device状态，再跑adb shell getprop ro.build.version.release能返回系统版本号，说明 shell 通道正常。这一步比单看 devices 更严格，因为有些设备 devices 显示 device 但 shell 实际不通。
第三步，trace 产出可用。抓一个短 trace 并检查文件大小和内容。
# 抓 3 秒 trace 并检查输出文件 python C:\Android\platform-tools\systrace\systrace.py -t 3 sched -o verify.html dir verify.htmlverify.html大小应该在几百 KB 到几 MB 之间，几 KB 说明没抓到数据。用浏览器打开，能看到时间轴和至少一条 sched 轨道才算成功。如果文件生成了但打开空白，回到 4.2 排查 category。
最后分享一个离线分析技巧：抓 trace 时加--from-file可以在没有设备的情况下重新解析已有 trace，配合-o输出不同格式。团队协作时，让出问题的同事把 trace 文件发过来，本地用同一版本脚本离线分析，省去远程连设备的麻烦。这个习惯帮我省过不少沟通成本。
从那以后我每次配新机器，都强制走一遍这三步验证，尤其是adb shell getprop那一步，宁可多花两分钟，也不想在排查性能问题时才发现环境是半残的。希望帮到你。
本文还有配套的精品资源，点击获取
