游戏引擎 / 系统课时

整理可复核的性能问题报告

整理可复核的性能问题报告

性能问题报告应让没有参与排查的同事复现同一长帧、打开对应采样证据,并独立确认修复效果。本篇以 Unity 6 战斗场景掉帧为例,把运行环境、操作路径、原始数据、代码改动和回归门槛整理成一份可核查的报告。

学习目标

  • 记录足以复现性能异常的设备、构建与操作条件。
  • 保存可以重新打开并定位到具体帧的 Profiler 证据。
  • 使用同口径数据说明改动效果,给出明确的通过或未通过结论。

锁定复现条件

报告标题写成“Android 真机进入 Arena 后转镜头出现 33 ms 以上长帧”,不要只写“游戏卡顿”。先给问题编号、发现版本和严重程度;以下 PERF-042 是演示工单,并非实测问题。

  1. 固定构建:记录 Unity 6 的完整版本号(例如 6000.0.xf1 应替换成真实补丁号)、Git 提交 SHA、Android/iOS 版本、IL2CPP 或 Mono、图形 API、渲染管线和画质档位。
  2. 固定设备:记录型号、GPU、屏幕实际渲染分辨率、刷新率、供电和温控状态。示例测试条件为目标 60 FPS、画质 High、动态分辨率关闭。
  3. 固定动作:冷启动后等待 30 秒,进入 Arena 场景再静置 30 秒;触发 50 个敌人入场,随后连续转动镜头 5 秒。保存操作录屏,按相同路径重复 3 轮。
  4. 定义异常:本例以单帧超过 33.3 ms 为可观察症状,同时统计整段样本中超过 16.67 ms 的帧比例。记录 3 轮中实际复现次数,不把一次偶发现象写成“必现”。

自动留下环境快照

将下面脚本保存为 Assets/Scripts/PerfEnvironmentLog.cs。它不需要挂到 GameObject;在 Unity 6 的编辑器运行或 Development Build 启动后记录一次环境,不在每帧打印日志。

csharp
using UnityEngine;

public static class PerfEnvironmentLog
{
#if UNITY_EDITOR || DEVELOPMENT_BUILD
    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterSceneLoad)]
    private static void Record()
    {
        // 记录运行时实际配置,避免报告只抄构建设置。
        string quality = QualitySettings.names[QualitySettings.GetQualityLevel()];
        // 这里只记环境;不能用这条日志替代帧耗时采样。
        Debug.Log($"[PerfEnv] unity={Application.unityVersion}; " +
                  $"app={Application.version}; platform={Application.platform}; " +
                  $"device={SystemInfo.deviceModel}; os={SystemInfo.operatingSystem}; " +
                  $"gpu={SystemInfo.graphicsDeviceName}; screen={Screen.width}x{Screen.height}; " +
                  $"quality={quality}; vSync={QualitySettings.vSyncCount}; " +
                  $"targetFps={Application.targetFrameRate}");
    }
#endif
}

预期输出(仅展示日志正文,各字段随真机与项目配置改变):

text
[PerfEnv] unity=<UNITY_VERSION>; app=<APP_VERSION>; platform=<PLATFORM>; device=<DEVICE>; os=<OS>; gpu=<GPU>; screen=<WIDTH>x<HEIGHT>; quality=<QUALITY>; vSync=<COUNT>; targetFps=<FPS>

复制实际日志到工单,另附构建产物标识与 Git 提交 SHA。targetFps=-1 只说明使用平台默认目标,不能据此认定屏幕正在以 60 Hz 运行;实际刷新率应另行核实。

保存可回放的采样证据

以 Unity 6.0 的窗口路径为例,在 File > Build Profiles 选目标平台,勾选 Development Build 和 Autoconnect Profiler,关闭 Deep Profiling Support,然后 Build and Run 到目标设备。在 Window > Analysis > Profiler 确认采样目标是 Player,不是 Editor。

  1. 在 Windows 的 Edit > Preferences > Analysis > Profiler 中把 Frame Count 设为 1200(macOS 从 Unity > Settings 进入),启用与现象有关的模块,例如 CPU Usage、Rendering;不要无差别打开高开销模块。
  2. 预热后开始记录,每轮截取约 900 帧;在 CPU Usage > Timeline 选中尖峰帧,记下帧编号、耗时和对应 Marker。重复 3 轮,每轮单独保存。
  3. 用 Profiler 的 Save 保存原始 .data 采样,并附一张含选中帧和 Timeline 细节的截图。文件可统一命名为 PERF-042-before-r1.data、PERF-042-before-r1.png;在报告中写明附件位置和对应帧号。
  4. 若问题表现为 GPU 长帧,必须补充目标平台可获得的 GPU 证据;设备不支持相关计数器时标注“未采集”,不要填写 0 ms。

.data 可用 Profiler 的 Load 再次打开,比只贴 FPS 截图更便于复核。Unity 6.0 操作可参照官方 Profiler 窗口文档。采样使用 Development Build,绝对耗时可能受采样开销影响,因此修复前后应保持相同采集配置。

用同一口径判定回归

修复记录至少写清:根因假设、证据中的 Marker 与帧编号、修改文件、前后 Git 提交以及可能影响性能的配置开关。例如“限制离屏敌人更新频率”应同时列出测试场景中敌人数量没有变化,而不是只留下“优化 AI”四个字。

以下数字是报告填写示例,假设在同一设备和构建配置下各采集 3 轮、每轮 900 帧,并对帧时间统一计算分位数;不是 Unity 自动生成的测量结果。

同口径指标 修复前 修复后 验收门槛
帧时间 P50 12.8 ms 11.9 ms 仅观察
帧时间 P95 27.6 ms 15.4 ms ≤16.67 ms
帧时间 P99 41.2 ms 18.9 ms ≤20 ms
超过 16.67 ms 的帧占比 18.0% 2.0% ≤3.0%

保存分位数的计算工具、版本及所用帧范围,避免把单帧最大值误写成 P99。以这组演示数据为例,三个门槛均通过;若操作过程中仍出现可复现的 33.3 ms 尖峰,不能仅凭汇总表关闭工单。

把证据链写进工单

报告中每条结论都要能回到原始输入:设备与版本对应一次复现,复现对应一份 .data,尖峰对应具体帧与 Marker,改动对应 Git 提交,最后由同条件回归决定是否关闭问题。

性能问题从复现条件到回归验收的证据链

交付前让另一名开发者按以下字段核对,而不是靠作者口头补充:

  • 定位与复现:PERF-042、设备和 Player 版本、步骤、复现成功次数、录屏。
  • 原始证据:修复前后每轮 .data、文件名、异常帧编号、截图与对应 Marker;附件链接必须有访问权限。
  • 修改记录:基线和修复的完整 Git SHA、变更文件、开关、可能的副作用。
  • 回归判定:采样工具与配置、帧数、P50/P95/P99、超预算比例、阈值及是否通过。

如果复核者无法打开采样、无法按步骤重现,或者前后设备与画质不同,应把报告标为“待补证”,不能标为“已修复”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

整理可复核的性能问题报告

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通