ios-performance-profiling

iOS 性能分析

目的

使用此技能选择合适的分析工作流、收集证据、解读性能信号，并在声称优化有效之前建议进行验证。

此技能用于选择分析路径并建立证据工作流。它不能取代针对启动性能、SwiftUI 性能、Swift Concurrency 性能、感知性能或 Swift 运行时开销的更具体技能。

何时使用此技能

当任务涉及以下内容时，使用此技能：

• 选择 Instruments 模板或性能分析工作流；
• 解读跟踪记录、屏幕截图、XCTest 指标、MetricKit 载荷、Organizer 数据、日志或 signpost；
• 诊断卡顿、动画掉帧、CPU 峰值、内存增长、泄漏、磁盘 I/O、网络延迟、功耗或生产环境回归；
• 设计优化前后的测量方案；
• 添加 signpost 或性能测试；
• 检查拟议的优化是否有证据支持。

何时不使用此技能

以下情况不要将此技能作为主要技能：

• 应用启动架构或启动关键工作，除非任务询问如何分析、测量或验证启动性能；
• SwiftUI 失效、身份标识、布局或滚动修复，除非任务询问应收集哪些分析证据；
• Swift Concurrency 设计或 Actor 隔离，除非任务询问如何分析任务行为、Actor 切换或与执行器相关的延迟；
• 感知性能、加载状态、骨架屏、乐观 UI 或反馈设计，除非任务询问如何验证感知延迟；
• Swift 运行时、ARC、分配、存在类型、泛型、分发或链接开销，除非任务询问如何测量这些开销。

如果用户已了解相关领域，需要的是修复方案而非测量工作流，请优先使用更具体的技能。

核心原则

先收集证据，再做优化。

使用以下循环：

Symptom -> reproducible scenario -> correct tool -> trace or metric -> hypothesis -> focused fix -> re-measure

如果没有验证路径，不要声称某项改动提升了性能。如果缺少证据，请说明哪些结论尚未得到证实，以及接下来应该测量什么。

能力检查

在建议或执行实际的性能分析工作流之前，先确认当前真正具备哪些条件。

请询问或推断：

• 是否有可构建的 Xcode 项目、工作区、方案和目标？
• 能否在真机上进行性能分析，还是只能在 Simulator 中进行？
• 是否有 Release 或类似发布版本的配置？
• 能否使用稳定数据和稳定应用状态复现该场景？
• 是否有可用的 Instruments 跟踪记录、屏幕截图、MetricKit 载荷、Organizer 屏幕截图、日志或 XCTest 结果？
• 能否将跟踪记录或报告作为工件分享？
• 任务要求的是性能分析计划、代码审查，还是解读现有证据？

如果缺少工具或工件，请提供测量计划，不要假装已经对应用进行了性能分析。

测量基线

性能分析时优先选择：

• UI、启动、功耗、内存压力、热行为和接近生产环境的响应性测试：优先使用真机，而非 Simulator；
• 优先使用 Release 或类似发布版本的构建，而非 Debug 构建；
• 多次运行，而非只测量一次；
• 使用稳定的输入数据和确定性的场景；
• 在报告中注明设备和 OS 信息；
• 当系统级跟踪范围过广时，在应用特定操作周围添加 signpost。

仅当问题关注相对性的本地调查，且明确说明其局限性时，才使用 Simulator。

工具选择

根据症状选择工具，而不是根据偏好的工作流选择。

症状或问题	主要工具	次要信号
冷启动、热启动、首帧、首次交互	App Launch、Time Profiler、XCTest 启动指标	MetricKit、Organizer、signposts
主线程卡顿或冻结	Hangs、Time Profiler	Main Thread Checker、signposts
动画卡顿、滚动卡顿、丢帧	Animation Hitches、Core Animation、Time Profiler	SwiftUI Instrument、signposts
SwiftUI 重复更新或大范围失效	SwiftUI Instrument	Time Profiler、signposts
CPU 峰值或操作缓慢	Time Profiler	Counters、signposts、XCTest 指标
内存增长、分配量高、内存周转频繁	Allocations、VM Tracker	Memory Graph、Leaks、XCTest 内存指标
保留循环或逻辑泄漏	Memory Graph Debugger	Allocations 代际分析
磁盘读写、持久化卡顿、写入过多	File Activity、System Trace	MetricKit 磁盘写入诊断
网络缓慢或重复请求	Network instrument、URLSession 指标	Signposts、服务器计时
电池耗电、热压力、唤醒	Energy Log、Power Profiler	MetricKit、Organizer
仅在生产环境出现的回归	MetricKit、Organizer	使用 Instruments 在本地复现
回归防护	XCTest 指标	CI 历史记录、MetricKit 发布版本对比

当信号与应用相关，且在系统工具中不够明显时，请在操作周围添加 os_signpost 或 OSSignposter。

跨技能路由

使用此技能选择并验证分析路径。必要时，将更深入的领域推理交由更专门的技能处理：

• 当证据指向 main 函数前的工作、dyld、静态初始化器、应用初始化、根场景构建、首帧、首次交互、SDK 启动、数据库预热或启动关键依赖链时，使用 ios-launch-performance。
• 当证据指向大范围状态读取、不必要的失效、不稳定的标识、耗时的布局、行复杂度、滚动行为或重复的 body 工作时，使用 swiftui-performance。
• 当证据指向任务激增、Actor 切换、MainActor 瓶颈、缺少取消、AsyncSequence 压力、执行器行为或导致 UI 延迟的异步工作时，使用 swift-concurrency-performance。
• 当证据表明应用确实在执行工作，但用户可见的问题是缺少反馈、加载状态不佳、渐进式渲染过晚或感知延迟时，使用 ios-perceived-performance。
• 当证据指向分配周转、ARC 流量、existentials、泛型、动态派发、写时复制、桥接、链接或运行时开销时，使用 swift-runtime-performance。

不要在此处重复这些技能的深入指导。

性能分析工作流

1. 确定用户可见的症状。
2. 定义可复现该问题的确切场景。
3. 根据症状选择主要分析工具。
4. 记录设备、OS、构建配置、数据集和运行次数。
5. 捕获最有力的信号：调用栈、帧卡顿、分配增长、保留路径、网络瀑布图、磁盘写入、唤醒或生产指标。
6. 区分数据能够证实的内容与只能暗示的内容。
7. 提出一两个按优先级排序的假设。
8. 建议最小且有针对性的修复，或下一步检查。
9. 使用相同场景重新测量。
10. 若问题足够重要，建议添加回归防护。

轨迹解读规则

阅读轨迹、报告或截图时：

• 优先关注最有力的信号，而不是罗列大量可能原因。
• 区分本地轨迹与生产环境指标。
• 区分 CPU 密集、受阻、等待、I/O 密集、内存压力和网络受限等症状。
• 检查这项开销是否位于用户可见的关键路径上。
• 谨慎看待平均值；对于卡顿、启动和生产环境延迟，p95 和 p99 往往更重要。
• 不要把一次顺利运行当作问题已修复的证据。
• 不要仅凭内存增长就推断存在引用循环；应检查所有权路径。
• 不要仅凭墙钟延迟就推断 CPU 开销；应用可能受阻于 I/O、锁、网络或主线程 Actor。

修复选择规则

只有在将修复与证据联系起来后，才提出建议。

优先考虑：

• 延后或移除关键路径上的工作；
• 缩小重复工作的范围；
• 减少重复请求或重复计算；
• 修复所有权链，而不是到处添加弱引用；
• 批量写入磁盘，或减少写放大；
• 为不可见或已过时的工作添加取消机制；
• 使用 signposts 和测试，让问题保持可观测。

避免：

• 缺乏轨迹证据就进行大范围重写；
• 未确认 UI 是否仍在等待的情况下，将工作移至后台队列；
• 尚未理清依赖关系就并行化工作；
• 优化不在关键路径上的代码；
• 声称某个工具证明了它实际并未测量的内容。

注意事项

• Instruments 用于解释本地原因；MetricKit 和 Organizer 用于识别生产环境信号。条件允许时两者都要使用。
• XCTest 性能测试比深入诊断更适合用于防止回归。
• Debug 构建可能会扭曲 CPU、分配、SwiftUI 和并发行为。
• 对于启动、滚动、内存压力、电量和热行为，模拟器结果可能会误导。
• 卡顿可能由主线程繁忙、锁竞争、同步 I/O、Actor 等待或依赖循环导致。不要假定是 CPU 饱和。
• 对于仍被引用的对象所形成的引用循环，Memory Graph 通常比 Leaks 更合适。
• 分配量激增不一定就是泄漏。应观察多代对象之间的增长，或检查保留的对象图。
• 即使本地 CPU 轨迹看起来正常，网络请求瀑布图也可能解释屏幕响应缓慢的原因。
• 功耗回归通常源于反复进行的小量工作：计时器、轮询、唤醒、后台任务、传感器、定位或屏幕外动画。
• 未通过可重复的前后测量验证前，不要宣称优化成功。

参考资料

仅在相关时阅读：

• references/tool-selection.md — 当任务需要更深入地将症状对应到 Instruments 模板、MetricKit、XCTest 指标、signpost 或生产诊断时阅读。
• references/time-profiler-and-hangs.md — 当任务涉及 Time Profiler、Hangs、主线程冻结、线程阻塞、锁竞争、同步 I/O、CPU 峰值或调用栈解读时阅读。
• references/animation-hitches-and-swiftui.md — 当任务涉及动画卡顿、滚动卡顿、丢帧、Core Animation、SwiftUI Instrument、重复视图更新、帧预算或 UI 响应性跟踪时阅读。
• references/memory-leaks-and-allocations.md — 当任务涉及 Allocations、Leaks、Memory Graph Debugger、VM Tracker、内存增长、引用循环、缓存、已解码图像或内存分配抖动时阅读。
• references/network-disk-power.md — 当任务涉及网络缓慢、重复请求、缓存行为、磁盘读写、持久化停顿、过多日志、后台工作、唤醒、电池消耗或热压力时阅读。
• references/xctest-metrickit-organizer.md — 当任务涉及 XCTest 性能测试、XCTApplicationLaunchMetric、CI 回归防护、MetricKit 负载、Xcode Organizer、生产环境回归、设备群组、p95 或 p99 时阅读。
• references/signposts-and-scenarios.md — 当任务需要可复现的场景、signpost 埋点、signpost 命名、自定义跟踪区间、前后对比或性能分析报告模板时阅读。

输出要求

对于大多数性能分析任务，请回复：

## Symptom

...

## Profiling path

Primary:
Secondary:
Why this tool:

## What to inspect

...

## Likely hypotheses

1. ...
2. ...

## Suggested fixes or next steps

...

## Verification

...

对于代码审查，请回复：

## Summary

...

## Findings

### 1. Finding title

Risk:
Why it matters:
Suggested change:
How to verify:

## Profiling checklist

...

对于跟踪记录、报告、日志、MetricKit 负载、Organizer 截图或 Instruments 截图，请回复：

## What the data shows

...

## Strongest signal

...

## Likely cause

...

## What is not proven yet

...

## Next step

...

## Verification

...

最终审核清单

在完成性能分析答复前，请检查：

• 是否指出了用户可感知的症状？
• 是否根据症状选择了工具？
• 是否说明了现有证据和缺失的信息？
• 是否区分了本地跟踪记录与生产指标？
• 是否考虑了设备、OS、构建配置、数据集和运行次数？
• 是否避免在缺乏证据时妄下定论？
• 是否在适当时建议使用真机进行 Release 性能分析？
• 是否在有用时建议为应用特定操作添加 signpost？
• 是否每次只提出一项有针对性的修复或后续检查步骤？
• 是否包含重新测量步骤？
• 是否在适当时建议使用 XCTest、MetricKit 或 Organizer 防止回归？
• 是否避免在证据不足时进行大范围重写？