ue5-debug-validation

快速入门

• 用最少步骤重现问题。
• 收集输出日志行以及相关 Actor／资源状态。
• 对故障域进行分类：数据、Blueprint、C++、网络或编辑器配置。

API 锚点（UE5.6-UE5.8）

• 核心诊断锚点：
  • UE_LOG(...)
  • ensure(...)、ensureMsgf(...)
  • check(...)、checkf(...)
• 运行时调试输出锚点：
  • UEngine::AddOnScreenDebugMessage(...)
  • UKismetSystemLibrary::PrintString(...)
• 结构化日志审查锚点：
  • FMessageLog::Info(...)
  • FMessageLog::Warning(...)
  • FMessageLog::Error(...)
• 资源／配置验证锚点：
  • FAssetRegistryModule、IAssetRegistry
  • GetAssetsByPath(...)
  • GetDependencies(...)、GetReferencers(...)

调试阶段约定

• 每项调试任务都必须定义：
  • 可重现的场景，以及预期行为与实际行为
  • 数据采集范围（日志、运行时状态、资源／配置快照）
  • 执行流水线中第一个异常转变的候选位置
  • 按可能性和验证成本排序的假设列表
  • 修复验证和回归范围
• 缺少任何一项，诊断输出都不完整。

工作流

1) 重现并固定上下文

• 使用精确步骤和前置条件构建最小、确定性的复现流程。
• 记录地图、Actor 设置、输入序列和运行时模式。
• 明确预期结果和实际偏差。

2) 捕获信号

• 按相关类别筛选日志，并关注故障时间窗口附近的时间戳。
• 如有需要，添加有针对性的调试标记（UE_LOG、屏幕调试输出或 Blueprint 打印）。
• 在各阶段边界捕获相关状态快照。

3) 验证数据和资源

• 验证关键资源／类／配置项是否存在且能正确解析。
• 检查依赖项／引用方，查找缺失或不匹配的资源。
• 确认运行时加载的数据与预期环境一致。

4) 定位第一个异常转变

• 逐步检查流水线，找出最早出现偏差的位置。
• 区分根本原因和下游噪声症状。
• 优先处理最小、可修复且置信度最高的原因。

5) 提出并验证假设

• 按可能性和验证成本对假设排序。
• 为每个假设进行一项有针对性的测试，避免相互干扰。
• 记录被否定的假设及其证据。

6) 修复并验证回归

• 应用最小修复，并重新运行相同的复现流程。
• 验证相邻系统／路径没有发生回归。
• 输出修复摘要，并说明置信度和剩余风险。

约束

• 诊断期间避免大范围重构。
• 保持复现流程确定且有文档记录。
• 优先采用可观测的检查，而非假设。
• 区分根本原因和次要噪声。
• 不要在同一步骤中混合修改检测手段和功能修复。
• 引入缓解性修改前，先保留故障证据。

故障处理

• 症状：无法稳定地重现问题。
  • 定位：前置条件缺失、竞态窗口或非确定性设置。
  • 修复：完善复现设置，并添加有针对性的检测检查点。
• 症状：日志中包含过多无关噪声。
  • 定位：日志类别范围过广，且缺少时间范围限定。
  • 修复：缩小类别筛选范围，并聚焦于故障时间戳附近。
• 症状：仍有多个可能的原因。
  • 定位：存在共同的下游症状，但尚未隔离首次故障。
  • 修复：拆分为独立假设，并进行成本较低、具有区分度的测试。
• 症状：添加调试输出后问题消失。
  • 定位：行为对时序／竞态敏感。
  • 修复：使用低开销标记，并在受控时序下重复测试。
• 症状：修复了一条路径，却破坏了另一条路径。
  • 定位：系统或配置层之间存在隐式耦合。
  • 修复：保持修复精简，并围绕受影响路径扩展回归矩阵。
• 症状：运行时不匹配仅发生在打包构建中。
  • 定位：构建配置／Cook 与编辑器运行之间存在差异。
  • 修复：比较打包版本和编辑器中的配置／资源，并验证加载顺序。

验证运维

• 始终在诊断中保留最小复现材料（步骤、地图、配置）。
• 始终提供首次失败的证据，而不只是最终症状日志。
• 始终为建议的修复提供验证清单。
• 当置信度未达到高时，始终说明残余风险。

UE5.6-UE5.8 兼容性说明

• 上文列出的日志、断言、消息和资源注册表 API 在 UE5.6-UE5.8 中保持稳定。
• 对于必须在编辑器外运行的验证路径，优先采用运行时安全的诊断方式。

升级处理

• 当故障出现在项目代码不负责的引擎或插件内部时，升级处理。
• 当诊断需要当前环境中不可用的平台专用性能分析工具时，升级处理。