游戏引擎 / 系统课时
添加自定义 Profiler 采样标记
添加自定义 Profiler 采样标记
Unity Profiler 默认能显示脚本更新和引擎调用的耗时,但未必能区分业务代码内部的筛选、排序或计算步骤。本课使用 ProfilerMarker 给关键代码块命名并记录耗时,让这些步骤直接出现在 CPU Timeline 中,从而判断具体是哪段逻辑拖慢了帧率。
学习目标
- 使用
ProfilerMarker和Auto()为 C# 业务代码添加计时范围。 - 在 CPU Timeline 和 Hierarchy 中识别自定义样本及父子关系。
- 根据采样耗时区分真正的热点,并避免标记范围和采样开销造成误判。
为什么需要自定义采样标记
假设背包系统每帧执行一次 Refresh(),其中包含物品筛选与排序。Profiler 可能已经显示 ScriptRunBehaviourUpdate 和脚本更新耗时,但这些默认样本不足以直接说明时间具体花在筛选还是排序上。
可以为三个业务范围分别命名:
| 标记名称 | 覆盖范围 | 排查目的 |
|---|---|---|
Inventory.Refresh |
完整刷新过程 | 判断整条业务路径的总耗时 |
Inventory.Filter |
物品条件筛选 | 检查遍历与过滤成本 |
Inventory.Sort |
可见物品排序 | 检查排序是否成为热点 |
Unity 6 提供位于 Unity.Profiling 命名空间中的 ProfilerMarker,无需为基本计时功能额外安装包。标记定义时指定名称,在执行目标代码前开始采样,结束时关闭采样范围。
推荐使用 Auto() 配合 C# 的 using 作用域。它在进入作用域时开始计时,并在退出时自动结束,避免异常或提前返回导致手动 Begin()、End() 不配对。
编写可运行的业务采样示例
下面建立一个可以独立运行的背包刷新测试脚本。它在启动时生成 20000 个整数物品编号,随后每帧筛选编号能被 3 整除的物品并排序。这里故意保留每帧排序,以便观察两段业务代码的耗时差异。
在 Unity 6.0(6000.0)及后续 Unity 6 版本中,新建 Assets/Scripts/InventoryProfilerDemo.cs,写入完整代码:
using System.Collections.Generic;
using Unity.Profiling;
using UnityEngine;
public sealed class InventoryProfilerDemo : MonoBehaviour
{
static readonly ProfilerMarker s_Refresh =
new ProfilerMarker("Inventory.Refresh");
static readonly ProfilerMarker s_Filter =
new ProfilerMarker("Inventory.Filter");
static readonly ProfilerMarker s_Sort =
new ProfilerMarker("Inventory.Sort");
[SerializeField, Range(1000, 100000)]
int itemCount = 20000;
readonly List<int> _items = new List<int>();
readonly List<int> _visible = new List<int>();
void Start()
{
// 预分配容量,避免测试期间因列表扩容干扰采样。
_items.Capacity = itemCount;
_visible.Capacity = itemCount;
for (int i = 0; i < itemCount; i++)
_items.Add((i * 73) % itemCount);
Debug.Log($"Inventory profiler demo ready: {_items.Count} items");
}
void Update()
{
// 外层标记覆盖完整刷新,内层分别测量筛选和排序。
using (s_Refresh.Auto())
{
using (s_Filter.Auto())
{
_visible.Clear();
foreach (int item in _items)
{
if (item % 3 == 0)
_visible.Add(item);
}
}
using (s_Sort.Auto())
{
_visible.Sort();
}
}
}
}预期输出:将脚本挂到场景中的激活对象上,进入 Play Mode 后,Console 出现一次初始化日志。保持默认 itemCount = 20000 时,输出为:
Inventory profiler demo ready: 20000 items同时,CPU Profiler 可以记录以下三个自定义样本:Inventory.Refresh、Inventory.Filter、Inventory.Sort。具体耗时取决于硬件、运行环境和当帧负载,不应预设固定毫秒数。
这里有两个容易忽略的实现细节。
首先,三个 ProfilerMarker 被声明为 static readonly,在类型初始化时创建并重复使用。不要在 Update() 或循环内部反复使用 new ProfilerMarker(...) 创建相同标记。
其次,Inventory.Refresh 是外层范围,内部依次执行筛选与排序。因此它的总耗时包含这两个子样本的耗时。不能把父样本与子样本的耗时直接相加,否则会重复计算。
在 CPU Timeline 中查找自定义样本
完成脚本后,按以下顺序验证:
- 在 Hierarchy 窗口创建空 GameObject,将
InventoryProfilerDemo挂到该对象上,确认组件已启用,Item Count为20000。 - 选择菜单
Window > Analysis > Profiler打开性能分析器。 - 在 Profiler 顶部选择编辑器 Play Mode 对应的采样目标,确认录制已开启,保持
Deep Profile关闭。 - 进入 Play Mode,运行若干帧,在
CPU Usage图表中选中一帧。 - 在下方详情视图选择
Timeline,展开Main Thread中的脚本更新相关样本,定位Inventory.Refresh。 - 展开对应的嵌套层级,检查其内部的
Inventory.Filter和Inventory.Sort,点击样本查看耗时。
Inventory.Refresh 是较长的父级时间条,两个子样本位于它的执行范围内,并按筛选、排序的实际执行顺序排列。它们不是三个互不相关的并行任务。

如果 Timeline 层级较深,也可以切换到 Hierarchy 视图,查看标记名称及其耗时统计。这里主要关注三个字段:
| 字段 | 含义 | 使用方法 |
|---|---|---|
Time ms |
样本总耗时,包含子样本 | 判断完整路径的时间成本 |
Self ms |
样本自身耗时,不包含子样本 | 判断父级是否还有未单独标记的热点 |
Calls |
当前帧样本调用次数 | 识别调用频率异常的逻辑 |
对于示例脚本,在正常执行的单帧中,三个标记通常各调用一次。如果同时存在多个挂载该脚本的激活对象,聚合后的调用次数会随实例数量增加。
根据采样结果判断优化位置
假设某帧记录到以下示意数据,单位均为毫秒:
| 样本 | 总耗时 | 自身耗时 |
|---|---|---|
Inventory.Refresh |
6.0 | 0.2 |
Inventory.Filter |
1.2 | 1.2 |
Inventory.Sort |
4.6 | 4.6 |
父级总耗时约为 6.0 ms,其中排序占 4.6 ms,说明这次采样中排序比筛选更值得优先排查。以上数值仅用于演示读取方法,并非示例在特定设备上的保证结果。
正确的下一步是检查排序触发条件,而不是直接改写所有循环。比如实际背包只有在物品新增、删除或排序规则变化时才需要重新排序,就可以设置脏标记,只在数据变化时调用 Sort()。
若背包每秒渲染 60 帧,但实际只发生一次物品变更,按需排序可使对应一秒内的排序调用次数从 60 次减少到 1 次。随后使用相同场景和采样条件重新测试,核对 Calls 与 Time ms 是否下降。
不过,减少排序调用不代表背包刷新整体一定满足性能预算,还需要同时检查其他系统的耗时和完整帧时间。
避免自定义标记造成新的误判
自定义标记适合围住完整、同步执行的业务阶段,但不适合无差别地插入每一行代码。实际项目可按以下原则检查:
- 控制标记粒度:优先围住背包刷新、NPC 决策、路径批处理等阶段。不要在 20000 次元素遍历的每次迭代中都创建独立采样范围,否则采样开销可能影响结果。
- 确保范围完整:
Auto()的作用域应覆盖需要比较的实际工作,避免把初始化、日志输出或其他无关操作混入被测范围。 - 避免跨越异步暂停:不要让
ProfilerMarker的采样范围跨越await或协程的yield return。需要分析跨帧任务时,应分别标记每次同步执行的阶段。 - 确认代码实际运行:若 Timeline 中找不到标记,先检查组件是否启用、采样目标是否正确、是否已经进入 Play Mode,以及当前选中帧是否执行了该代码。
Unity 6 的 ProfilerMarker.Begin() 和 End() 在非 Development 的 Release 构建中会被条件编译移除;Auto() 不能完全以相同方式编译消除,但在该环境下只有很小的额外开销。需要对比实际运行性能时,仍应优先使用目标设备上的 Development Build 进行采样,并保持各次测试配置一致。
与开启全局 Deep Profile 相比,针对已知可疑路径添加少量自定义标记,通常能以更低的采样开销回答具体问题。最终应保留具有诊断价值的标记,并通过优化前后的相同场景采样确认收益。