介绍
# Instruments Profiling (macOS/iOS)
当用户希望对原生应用进行性能分析或堆栈分析时，请使用此技能。 重点：Time Profiler（时间分析器）、`xctrace` CLI，以及选择正确的二进制文件/应用实例。
## 快速开始 (CLI)
- 列出模板：`xcrun xctrace list templates` - 记录 Time Profiler（启动）： - `xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --launch -- /path/To/App.app` - 记录 Time Profiler（附加）： - 手动启动应用，获取 PID，然后执行： - `xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --attach <pid>` - 在 Instruments 中打开 trace 文件： - `open -a Instruments /tmp/App.trace`
注意：`xcrun xctrace --help` 不是有效的子命令。请使用 `xcrun xctrace help record`。
## 选择正确的二进制文件（关键）
**注意：Instruments 可能会分析错误的应用**（例如 `/Applications` 中的应用），如果 LaunchServices 解析到了不同的 Bundle。 请遵循以下规则：
- 优先使用直接二进制路径以进行确定性启动： - `xcrun xctrace record ... --launch -- /path/App.app/Contents/MacOS/App` - 如果启动 `.app`，确保它是预期的 Bundle： - `open -n /path/App.app` - 使用 `ps -p <pid> -o comm= -o command=` 验证 - 如果同时存在 `/Applications/App.app` 和本地构建版本，请显式指定本地构建的路径。 - 启动后，在信任 trace 结果之前确认进程路径。
## 命令参数
- `--template 'Time Profiler'`：来自 `xctrace list templates` 的模板名称。 - `--launch -- <cmd>`：`--` 之后的所有内容均为目标命令（二进制文件或 App Bundle）。 - `--attach <pid|name>`：附加到正在运行的进程。 - `--output <path>`：`.trace` 输出文件。如果省略，文件将保存在当前工作目录 (CWD)。 - `--time-limit 60s|5m`：设置捕获持续时间。 - `--device <name|UDID>`：iOS 设备运行所必需。 - `--target-stdout -`：将启动进程的 stdout 流式传输到终端（对 CLI 工具很有用）。
## 导出堆栈 (CLI)
- 检查 trace 表： - `xcrun xctrace export --input /tmp/App.trace --toc` - 导出原始 time-profile 采样数据： - `xcrun xctrace export --input /tmp/App.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="time-profile"]' --output /tmp/time-profile.xml` - 在脚本（Python/Rust）中进行后处理以聚合堆栈。
## Instruments UI 工作流
- 模板：Time Profiler - 使用“Record”并捕获慢速路径（启动阶段 vs 稳定状态） - 调用树技巧： - 隐藏系统库 - 反转调用树 - 按线程分离 - 关注热点帧和调用计数
## 常见问题与修复
- **分析了错误的应用**：LaunchServices 解析到了已安装的应用，而不是本地构建版本。 - 修复：使用直接二进制路径，或使用 `--attach` 配合已知的 PID。 - **无采样 / 空 trace**：应用退出太快或从未执行工作。 - 修复：延长捕获时间，在记录期间触发工作负载。 - **隐私提示**：`xctrace` 可能需要“开发者工具”权限。 - 修复：系统设置 → 隐私与安全性 → 开发者工具 → 允许终端/Xcode。 - **XML 导出文件过大**：`time-profile` 导出文件非常巨大。 - 修复：使用 XPath 过滤并离线聚合；不要打印到终端。
## iOS 特别说明
- 设备：使用 `xcrun xctrace list devices` 和 `--device <UDID>`。 - 如有必要，通过 Xcode 启动；使用 `xctrace --attach` 附加。 - 确保存在调试符号以获取有意义的堆栈。
## 验证清单
- 确认 trace 进程路径与目标构建版本匹配。 - 确认堆栈显示了预期的应用帧。 - 捕获覆盖了慢速操作（启动/刷新）。 - 如果正在优化，请导出堆栈以进行自动化对比。