游戏引擎 / 系统课时
整理可复核的性能问题报告
整理可复核的性能问题报告
性能问题报告应让没有参与排查的同事复现同一长帧、打开对应采样证据,并独立确认修复效果。本篇以 Unity 6 战斗场景掉帧为例,把运行环境、操作路径、原始数据、代码改动和回归门槛整理成一份可核查的报告。
学习目标
- 记录足以复现性能异常的设备、构建与操作条件。
- 保存可以重新打开并定位到具体帧的 Profiler 证据。
- 使用同口径数据说明改动效果,给出明确的通过或未通过结论。
锁定复现条件
报告标题写成“Android 真机进入 Arena 后转镜头出现 33 ms 以上长帧”,不要只写“游戏卡顿”。先给问题编号、发现版本和严重程度;以下 PERF-042 是演示工单,并非实测问题。
- 固定构建:记录 Unity 6 的完整版本号(例如
6000.0.xf1应替换成真实补丁号)、Git 提交 SHA、Android/iOS 版本、IL2CPP 或 Mono、图形 API、渲染管线和画质档位。 - 固定设备:记录型号、GPU、屏幕实际渲染分辨率、刷新率、供电和温控状态。示例测试条件为目标 60 FPS、画质 High、动态分辨率关闭。
- 固定动作:冷启动后等待 30 秒,进入
Arena场景再静置 30 秒;触发 50 个敌人入场,随后连续转动镜头 5 秒。保存操作录屏,按相同路径重复 3 轮。 - 定义异常:本例以单帧超过 33.3 ms 为可观察症状,同时统计整段样本中超过 16.67 ms 的帧比例。记录 3 轮中实际复现次数,不把一次偶发现象写成“必现”。
自动留下环境快照
将下面脚本保存为 Assets/Scripts/PerfEnvironmentLog.cs。它不需要挂到 GameObject;在 Unity 6 的编辑器运行或 Development Build 启动后记录一次环境,不在每帧打印日志。
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
}预期输出(仅展示日志正文,各字段随真机与项目配置改变):
[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。
- 在 Windows 的
Edit > Preferences > Analysis > Profiler中把Frame Count设为 1200(macOS 从Unity > Settings进入),启用与现象有关的模块,例如CPU Usage、Rendering;不要无差别打开高开销模块。 - 预热后开始记录,每轮截取约 900 帧;在
CPU Usage > Timeline选中尖峰帧,记下帧编号、耗时和对应 Marker。重复 3 轮,每轮单独保存。 - 用 Profiler 的
Save保存原始.data采样,并附一张含选中帧和 Timeline 细节的截图。文件可统一命名为PERF-042-before-r1.data、PERF-042-before-r1.png;在报告中写明附件位置和对应帧号。 - 若问题表现为 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、超预算比例、阈值及是否通过。
如果复核者无法打开采样、无法按步骤重现,或者前后设备与画质不同,应把报告标为“待补证”,不能标为“已修复”。