Unity Debug

Unity Debug

系统地诊断和修复 Unity Bug。追踪执行路径，找出根本原因，提出修复方案和预防措施。

此 Skill 的作用

1. 收集症状（错误消息、堆栈跟踪、描述）
2. 对 Bug 类型进行分类
3. 阅读相关代码
4. 按类别应用诊断树
5. 提出修复方案并说明原因
6. 添加防御性代码和预防建议

前置条件

• 能访问 Unity 项目的源文件
• 理想情况下：提供准确的错误消息或堆栈跟踪
• 仅使用 Claude Code 工具（Read、Grep、Glob）——不需要 MCP Unity

快速开始

1. 用户描述 Bug 或粘贴错误信息
2. 对 Bug 类型进行分类（参见类别）
3. 阅读相关文件
4. 按照诊断树进行排查
5. 按以下格式输出诊断：症状 | 原因 | 修复方案 | 预防措施

---

决策树

Le bug est...
|
+-- Erreur de compilation (code rouge, pas de Play)
|   +-- COMPILE ERROR -> verifier syntaxe, references, asmdef
|
+-- Exception a l'execution (message en console, peut crasher)
|   +-- NullReferenceException        -> ARBRE NULL REF
|   +-- MissingComponentException     -> ARBRE MISSING COMPONENT
|   +-- MissingReferenceException     -> ARBRE DESTROYED OBJECT
|   +-- IndexOutOfRangeException      -> verifier tailles collections
|   +-- InvalidOperationException     -> verifier etat collection pendant iteration
|   +-- StackOverflowException        -> verifier recursion / boucle d'events
|   +-- OperationCanceledException    -> ARBRE ASYNC/AWAITABLE
|
+-- Comportement incorrect (pas d'erreur visible)
|   +-- LOGIC BUG -> tracer le chemin d'execution
|
+-- Performance (lag, stutter, freeze)
|   +-- Bug de perf specifique -> PERF ISSUE -> chercher allocations, Update lourd, physics
|   +-- Audit systematique     -> utiliser /perf-audit a la place
|
+-- Probleme visuel (rendu, UI, shader)
|   +-- VISUAL GLITCH -> verifier materials, sorting, render pipeline
|
+-- Probleme physique (traverse les murs, jitter)
|   +-- PHYSICS BUG -> verifier Update vs FixedUpdate, layers, scale
|
+-- Probleme async / Awaitable
    +-- ASYNC BUG -> ARBRE ASYNC/AWAITABLE

分步指南

1 — 收集症状

向用户获取以下信息：

• 准确的错误消息（完整复制，包括堆栈跟踪）
• 发生时机（启动时、执行某项操作后、随机发生）
• 是否可复现（始终发生、偶尔发生、仅在构建版本中发生）
• 近期变更（故障发生前修改了什么）

如果有堆栈跟踪，请提取：

• 文件和行号（at Namespace.Class.Method () in File.cs:line X）
• 调用链（谁调用了谁）

2 — 阅读相关文件

Grep("class NomDuScript", type: "cs")        -> trouver le fichier
Read(fichier identifie)                       -> lire le code complet
Grep("GetComponent|Find|SendMessage", fichier) -> reperer les appels risques
Grep("void Update|void FixedUpdate", fichier)  -> reperer les hot paths

对于堆栈跟踪，应从最深层到最上层，阅读调用链中提到的每个文件。

3 — 应用诊断树

详细诊断树请参见 references/diagnostic-trees.md

4 — 提出修复方案

输出格式

每项诊断都必须采用以下格式：

## Diagnostic

**Symptome** : [description precise de ce qui se passe]
**Cause** : [explication technique de pourquoi ca arrive]
**Fix** : [code corrige avec diff ou snippet]
**Prevention** : [comment eviter ce bug a l'avenir]

防御性代码 — 模式

// Null check avec log explicite
if (_target == null)
{
    Debug.LogWarning($"[{name}] Target reference is missing.", this);
    return;
}

// TryGetComponent au lieu de GetComponent
if (!TryGetComponent(out Rigidbody rb))
{
    Debug.LogError($"[{name}] Missing Rigidbody.", this);
    return;
}

// Verifier destruction avant callback
private IEnumerator DelayedAction()
{
    yield return new WaitForSeconds(1f);
    if (this == null) yield break;  // objet detruit pendant le wait
    DoAction();
}

// Desubscription propre
private void OnEnable() => _eventChannel.Subscribe(OnEvent);
private void OnDisable() => _eventChannel.Unsubscribe(OnEvent);

---

严格规则

始终：

• 诊断前先阅读实际源代码
• 追踪完整的执行路径（没有证据就不要推断）
• 除修复方案外，还要提出预防措施
• 从最简单的解释开始（奥卡姆剃刀）
• 检查 Inspector 引用（未赋值的 [SerializeField] 字段）
• 检查 Unity 生命周期顺序（Awake -> OnEnable -> Start）
• 按 症状 | 原因 | 修复方案 | 预防措施 格式提供诊断

绝不：

• 不阅读代码就猜测原因
• 不理解根本原因就提出修复方案
• 不忽略堆栈跟踪（每一行都是线索）
• 不将 try/catch 作为修复方案（它会掩盖 Bug，而不能解决问题）
• 不要假设 Bug 出在 Unity Engine 中（几乎总是用户代码的问题）
• 不提出会引入新问题（回归问题）的修复方案

---

相关 Skills

• 如果 Bug 是一般性能问题，而非特定情况，请使用 /perf-audit（Unity Perf Audit）
• 如果修复需要大规模重构，请使用 /unity-refactor（Unity Refactor）
• 如果修复需要通过测试进行验证，请使用 /unity-test（Unity Test）

故障排查

问题	解决方案
没有可用的堆栈跟踪	请用户在打开控制台的情况下重现问题，或查找现有的 Debug.Log 以进行跟踪
Bug 无法重现	查找竞态条件，检查问题是否取决于场景加载顺序或帧率
第三方包中的错误	阅读包的代码（Library/PackageCache/），查找已知问题，并提出变通方案
仅在构建版本中出现的 Bug（Editor 中不会出现）	检查：代码剥离（IL2CPP）、序列化差异、错误放置的 #if UNITY_EDITOR、运行时修改的 SO
与帧率相关的间歇性 Bug	查找 Update 中依赖帧的代码，确认其是否应放在 FixedUpdate 中，或是否存在未使用 epsilon 的浮点数比较
性能逐渐下降	查找泄漏：未取消订阅的事件、不断增长但未清空的列表、未使用对象池而实例化的对象

---

常见 Bug 表：参见 references/common-bugs.md