project-auditor-fixes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Project Auditor Project Auditor carries out a static analysis scan of the Unity Project and reports a list of CSV issues that may be fixed. Trigger, poll, read.

使用 Project Auditor Project Auditor 会对 Unity 项目执行静态分析扫描，并输出可修复的 CSV 格式问题列表。操作流程为：触发、轮询、读取。

Prerequisites

前置条件

To use Project Auditor you'll need the Unity CLI installed - see the unity-cli skill for more details. Once you have that, the audit and audit_status commands run Project Auditor checks.

bash

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

audit_status

terminal status are

completed

(with

csvPath

issueCount

failed

unavailable

, and

interrupted

(a domain reload killed the scan — just re-run

audit

). Polling is responsive while a scan compiles assemblies and is busy on the main thread. You can only run one scan at a time: a second

audit

returns

busy

. There is no cancel — stop polling to abandon a scan.

The output CSV has columns:

Category, Severity, Areas, Description, RelativePath, Line, DescriptorId, Recommendation

(these are diagnostics only, so every row is something to fix;

Recommendation

says how to do it).

Requires Project Auditor plus its rules.
unavailable
means the Editor has no Project Auditor, or it has no analysis rules — in a built-in-module Editor the rules live in the separate
com.unity.project-auditor-rules
package (
unity command package_add --identifier com.unity.project-auditor-rules --confirm true
). Read the
message
field; the command never reports an empty
completed
scan that would look like a clean project.

要使用 Project Auditor，你需要安装 Unity CLI——更多详情请查看 unity-cli skill。安装完成后，可通过 audit 和 audit_status 命令运行 Project Auditor 检查。

bash

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
表示编辑器未安装 Project Auditor，或没有分析规则——在内置模块版的编辑器中，规则存放在独立的
com.unity.project-auditor-rules
包中（可通过
unity command package_add --identifier com.unity.project-auditor-rules --confirm true
安装）。请查看
message
字段；该命令永远不会返回空的
completed
扫描结果（即看起来项目没有问题的情况）。

Gotchas

注意事项

set_autotick
first. Without it, recompile and tests can hang while the editor is unfocused. The package's watchdog relies on the tick loop staying alive.
Hot reload needs the game running.
```
reload_file_override
```
/
```
reload_file
```
apply to a live game — enter Editor Play Mode (
```
unity command editor_play
```
) first, or run a dev Player.
Player-only commands need a dev Player.
```
log
```
,
```
set_timescale
```
,
```
runtime_status
```
, etc. hit the Runtime server, which does not run in the Editor.
Async commands poll.
```
recompile
```
→
```
recompile_status
```
,
```
run_tests --async_tests
```
→
```
test_status
```
. Never assume completion from the trigger call's response.
Target a specific instance with
```
--instance host:port
```
or
```
--project-path <path>
```
when more than one is running.

请先执行
set_autotick
。否则，当编辑器失去焦点时，重新编译和测试可能会挂起。该包的看门狗依赖于持续运行的 tick 循环。
热重载需要游戏处于运行状态。
```
reload_file_override
```
/
```
reload_file
```
仅适用于运行中的游戏——请先进入编辑器 Play Mode（
```
unity command editor_play
```
），或运行开发版 Player。
仅 Player 端可用的命令需要开发版 Player。
```
log
```
、
```
set_timescale
```
、
```
runtime_status
```
等命令会访问 Runtime 服务器，该服务器不会在编辑器中运行。
异步命令需要轮询。 例如
```
recompile
```
→
```
recompile_status
```
，
```
run_tests --async_tests
```
→
```
test_status
```
。切勿仅通过触发调用的响应就认为操作已完成。
指定目标实例 当运行多个实例时，可通过
```
--instance host:port
```
或
```
--project-path <path>
```
来指定目标实例。

Best Practice

最佳实践

When fixing a list of issues it's best practice to have a test case to make sure things are still working correctly. This might be a particular scene to open and start play mode, or a particular platform to build and run. If this isn’t present and there are no instructions, suggest a test case to the user and ask for confirmation. Run the test case before and after changes to make sure the project is still working.

As you work, make sure any changes are committed in alignment with user version control setup. Wherever possible, commit step-by-step, breaking things down into changes that a user can easily understand.

修复问题列表时，最佳实践是准备一个测试用例，以确保功能仍能正常运行。测试用例可以是某个需要打开并进入 play mode 的特定场景，或是某个需要构建并运行的特定平台。如果没有测试用例且没有相关说明，应向用户建议一个测试用例并请求确认。在修改前后都要运行测试用例，确保项目仍能正常工作。

工作过程中，请确保所有修改都按照用户的版本控制设置进行提交。尽可能分步提交，将修改拆分为用户容易理解的小单元。

Recipe

操作步骤

Make sure the project opens cleanly (with no compile or other errors in the Editor). If there are issues present, check with the user; they may know about them and want to ignore them. Run the test case and make sure you know what state it's in, fixing things if necessary.
Commit any changes so that we start the upgrade process with clean version control.
Open the project in the Unity Editor. Then use Unity CLI to run the audit command.
Group the issues by file and by type.
Choose a type of issue to work through one group or file at a time. 5.a. Default to fixing settings issues on assets or the projects by type. 5.b. Default to fixing code issues by file and subfolder. 5.c. However, it’s important to fix issues in human manageable and reviewable batches. 5.c.i. Making the same small change across a large number of files (for example, switching a boolean setting across many textures) is probably best done in one commit, or a commit per subfolder. 5.c.i.. When making code changes, the code should compile between each commit. 5.d. Make changes based on the recommendations from Project Auditor. Commit each change once there are no errors in the editor.

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