Unity Perf Audit

Unity 性能审计

此技能的功能

对 Unity 项目的 C# 代码进行静态分析，以检测性能反模式。无需运行游戏或进行性能分析——只需使用 Grep 和 Glob 扫描源代码。

产出：

• Unity 项目 C# 文件清单（数量、大小、较大的文件）
• 检测到的反模式报告，包含严重性和位置
• 优先级最高的 5 项修复建议，附修复前后的代码

前置条件

• Unity 项目，且 Assets/ 中包含 C# 脚本
• 对项目文件夹拥有读取权限
• 无需任何程序包或外部工具

决策树

Symptome rapporte ?
|
+-- FPS bas en general --> Lancer le scan complet (etapes 1-5)
+-- Spikes ponctuels / stuttering --> Focus CPU (anti-patterns C1-C12)
+-- Memoire qui grimpe / crashs OOM --> Focus Memory (anti-patterns M1-M7)
+-- Rendu lent, draw calls hauts --> Focus GPU (anti-patterns G1-G5)
+-- Pas de symptome precis (audit preventif) --> Scan complet

快速开始

1. 扫描项目结构（Glob **/*.cs）
2. 检测 CPU、GPU、内存方面的反模式（Grep）
3. 为每个问题评分并分类
4. 生成报告，标注文件:行号
5. 提出优先级最高的 5 项修复建议

分步指南

步骤 1：扫描项目结构

使用 Glob 清点项目中的所有 C# 文件。

Glob: Assets/**/*.cs

分析：

• .cs 文件总数
• 找出超过 500 行的文件（使用 Read 统计行数或运行 wc -l）
• 找出脚本最多的文件夹（了解项目结构）
• 排除 Plugins/、ThirdParty/、TextMesh Pro/ 文件夹（外部代码）

统计所有文件行数的 Bash 命令：

find <project>/Assets -name "*.cs" -not -path "*/Plugins/*" -not -path "*/ThirdParty/*" -not -path "*/TextMesh Pro/*" | xargs wc -l | sort -rn | head -20

生成摘要：

## Structure projet
- **Fichiers C#** : 47
- **Lignes totales** : 12,340
- **Fichiers > 500 lignes** : PlayerManager.cs (623), GameController.cs (891)
- **Dossiers principaux** : Scripts/ (28), UI/ (12), Enemies/ (7)

步骤 2：检测反模式

扫描 C# 文件中的 CPU、GPU 和内存反模式。完整的待检测模式列表见 references/anti-patterns.md。

对于每个匹配项，记录文件、行号和代码行。使用 Grep 搜索项目中所有 .cs 文件（排除指定目录）。

步骤 3：评分并分类

为每个文件和整个项目评分：

严重性	分数	影响
严重	10	直接导致明显卡顿（每帧都会发生）
高	5	高负载下会造成显著性能下降
中	2	可通过性能分析器测量到影响
低	1	属于最佳实践，影响极小

总分：

• 0-10：良好。无需采取行动。
• 11-30：尚可。有一些问题需要修复。
• 31-60：存在问题。建议在构建前修复。
• 61+：严重。必须修复。

仅对代码中确实存在的问题评分。绝不要臆造假设性问题。

步骤 4：生成报告

报告格式：使用包含 #、问题、严重性、文件:行号、说明 列的表格。按严重性分组（严重 > 高 > 中 > 低）。按严重性添加摘要（数量 + 分数）。附上总分和结论（良好 / 尚可 / 存在问题 / 严重）。

步骤 5：提出优先级最高的 5 项修复建议

针对每项修复，展示修复前后的代码。按严重性排序问题（优先处理严重问题）。格式：标题、严重性、行号、影响，然后是修复前后的代码。

常见修复模式：

反模式	标准修复方法
在 Update 中调用 GetComponent	在 Awake 中缓存到私有字段
运行时调用 Find	在 Awake 中缓存，或通过 SerializeField 注入
在 Update 中调用 Camera.main	private Camera _cam; void Awake() => _cam = Camera.main;
在 Update 中进行字符串拼接	使用 StringBuilder 或 string.Format，或移除日志
在 Update 中调用 Instantiate	使用对象池（Queue + 激活/停用）
在 Update 中使用 foreach	使用 List<T> 和 for 循环
SendMessage	使用直接接口调用或 C# 事件
.tag ==	使用 .CompareTag("name")
重复调用 new WaitForSeconds	缓存为 static readonly WaitForSeconds
事件未取消订阅	在 OnDisable() 或 OnDestroy() 中添加 -=
调用 Resources.Load 后未卸载	使用后添加 Resources.UnloadUnusedAssets()，或改用 Addressables

严格规则

始终：

• 仅报告实际代码中发现的问题（不要提出假设）
• 针对每个问题，注明确切的文件和行号
• 提供包含修改前后代码的具体修复方案
• 按影响程度排序（Critical 优先）
• 排除第三方代码（Plugins/、ThirdParty/、TextMesh Pro/）
• 检查上下文：在 Start() 中调用 GetComponent 可以接受，在 Update() 中则不可以

绝不：

• 建议优化只执行一次的代码（Start、Awake、初始 OnEnable、loading screens）
• 虚构代码中不存在的问题
• 建议大规模重构（只修复热路径，不调整架构）
• 建议使用外部工具或付费软件包
• 将热路径之外对固定集合进行的 foreach 报告为问题
• 忽略误报：报告前确认该模式确实处于有问题的上下文中

相关 Skills

• 需要诊断特定的性能问题（崩溃、偶发卡顿）？使用 /unity-debug（Unity Debug）
• 需要通过结构性重构应用检测到的修复？使用 /unity-refactor（Unity Refactor）
• 需要在修复后进行测试？使用 /unity-test（Unity Test）

故障排除

问题	解决方案
GetComponent 误报太多	检查所在方法。在 Awake/Start/OnEnable 中调用 GetComponent 不算问题。在 Grep 中使用 -B 20 查看上下文。
在注释中检测到模式	过滤以 // 开头或位于 /* */ 块中的行。阅读文件以确认。
文件过大，无法分析	使用 offset/limit 分段读取。重点检查 Update、FixedUpdate、LateUpdate 方法。
项目没有 Assets/ 文件夹	检查项目路径。请用户确认 Unity 项目根目录。
原型项目的得分很高	结合上下文说明：原型项目不需要深度优化。指出问题，但降低紧急程度。
在已停用的代码中发现反模式	检查是否存在 #if / [System.Obsolete] / 表示代码已废弃的注释。不要报告已废弃的代码。
未找到 .cs 文件	项目可能为空，或脚本位于软件包中。使用 Glob **/*.cs（不限制文件夹）进行检查。
Event leak 误报	检查模式：如果 += 位于 OnEnable 中，且 -= 位于 OnDisable 中，则没有问题。也要检查匿名 lambda（无法取消订阅）。

完整的反模式表：请参阅 references/anti-patterns.md