project-auditor-fixes

使用 Project Auditor Project Auditor 会对 Unity 项目执行静态分析扫描，并报告一份可能需要修复的问题 CSV 列表。触发、轮询、读取。

前提条件

要使用 Project Auditor，你需要安装 Unity CLI；详情请参阅 unity-cli 技能。 完成安装后，audit 和 audit_status 命令即可运行 Project Auditor 检查。

unity command audit                              # optional: --categories Code,ProjectSetting --output my.csv
unity command audit_status                       # repeat until a terminal status is returned

audit_status 的终端状态包括 completed（包含 csvPath 和 issueCount）、failed、unavailable 和 interrupted（域重载终止了扫描——只需重新运行 audit）。扫描正在编译程序集且主线程繁忙时，轮询仍能及时响应。一次只能运行一个扫描：第二个 audit 会返回 busy。没有取消功能——停止轮询即可放弃扫描。

输出的 CSV 包含以下列：Category, Severity, Areas, Description, RelativePath, Line, DescriptorId, Recommendation （这些仅是诊断信息，因此每一行都表示需要修复的问题；Recommendation 会说明如何修复）。

需要安装 Project Auditor 及其规则。 unavailable 表示 Editor 中没有 Project Auditor， 或者没有分析规则——在内置模块 Editor 中，规则位于单独的 com.unity.project-auditor-rules 包中（unity command package_add --identifier com.unity.project-auditor-rules --confirm true）。请读取 message 字段；命令绝不会报告一个看似项目干净的空 completed 扫描。

注意事项

• 先运行 set_autotick。 否则，在 Editor 未获得焦点时，重新编译和测试可能会卡住。该包的看门狗依赖持续运行的 tick 循环。
• 热重载需要游戏正在运行。 reload_file_override / reload_file 只对运行中的游戏生效——请先进入 Editor Play Mode（unity command editor_play），或运行开发版 Player。
• 仅适用于 Player 的命令需要开发版 Player。 log、set_timescale、runtime_status 等命令会访问 Runtime 服务，该服务不会在 Editor 中运行。
• 异步命令需要轮询。 recompile→recompile_status，run_tests --async_tests→ test_status。不要假设触发调用的响应就表示任务已完成。
• 有多个实例运行时，使用 --instance host:port 或 --project-path <path> 指定目标实例。

最佳实践

修复问题列表时，最佳做法是准备一个测试用例，以确保功能仍然正常。这可以是一个需要打开并进入播放模式的特定场景，也可以是一个需要构建并运行的特定平台。如果没有测试用例，也没有相关说明，请向用户建议一个测试用例并征求确认。在更改前后都运行该测试用例，以确保项目仍正常运行。

在工作过程中，请确保根据用户的版本控制设置提交所有更改。尽可能逐步提交，将更改拆分成用户容易理解的部分。

流程

1. 确保项目能够正常打开（编辑器中没有编译错误或其他错误）。如果存在问题，请先与用户确认；他们可能了解这些问题，并希望忽略它们。运行测试用例，确认当前状态，并在必要时修复问题。
2. 提交所有更改，以便在干净的版本控制状态下开始升级流程。
3. 在 Unity 编辑器中打开项目。然后使用 Unity CLI 运行审计命令。
4. 按文件和类型对问题分组。
5. 选择一种问题类型，每次处理一组问题或一个文件。 5.a. 默认按类型修复资源或项目的设置问题。 5.b. 默认按文件和子文件夹修复代码问题。 5.c. 但重要的是，要以人工能够处理和审核的批次修复问题。 5.c.i. 在大量文件中进行相同的小改动（例如，更改许多纹理的布尔设置），最好在一次提交中完成，或按子文件夹分别提交。 5.c.i.. 进行代码更改时，每次提交之间都应确保代码能够编译。 5.d. 根据 Project Auditor 的建议进行更改。编辑器中没有错误后，提交每项更改。