API 更新程序

为了提高可用性和性能，Unity 可能会改变类、函数和属性（API）的工作方式。有时，这些改进可能会在从一个主要 Unity 版本迁移到另一个主要 Unity 版本时引入重大更改。

为了最大程度地减少中断性变更的影响，API 更新程序会识别并更新您脚本一段代码，允许您创建自己的组件、触发游戏事件、随时间修改组件属性以及以您喜欢的任何方式响应用户输入。更多信息
请参阅术语表和集会。

API 更新程序由 ScriptUpdater 和 AssemblyUpdater 组成，它们分别负责更新源代码（脚本）和程序集（dll 文件）。

注意：API 更新程序只能修复 API 中的某些错误和警告。这些在控制台消息中指示为 UnityUpgradable。您必须手动解决 API 更新程序无法处理的其他错误或警告。

使用 API 更新程序

触发脚本编译时，API 更新程序会自动运行。例如，当您：

• 打开一个项目。
• 导入包。
• 保存对脚本的更改。

API 更新程序提供更新它检测到的任何过时代码。如果接受，它会使用建议的 API 更新版本重写任何过时的代码。

例如，API 更新程序会将以下过时语句从以下位置转换：

light.color = Color.red;

自：

GetComponent<Light>().color = Color.red;

以下步骤描述了 Unity 触发脚本编译时 API 更新程序的工作流程：

1. Unity 会触发脚本编译。
2. API 更新程序检查它可以处理的可更新编译器错误或警告。
   • 如果未发现任何错误或警告，则该过程结束。
   • 如果发现任何错误或警告，它会显示一个提供自动更新的对话框。
     关闭编辑器并备份项目，然后再让API更新程序更新脚本或程序集。当您重新打开项目时，Unity 会编译您的脚本并触发 API 更新程序。
3. 如果您接受更新，API 更新程序将更新同一编译单元中的所有脚本。
4. API 更新程序会重复此过程，直到它检测到无法处理的更多错误或警告。

如果具有过时代码的脚本属于不同的编译通道（例如编辑器脚本），则更新程序可以多次运行。

如果您不允许 API 更新程序更新您的脚本，则控制台会显示任何脚本错误或警告。API 更新程序可以解决的错误或警告显示在消息中 （UnityUpgradable）。

如果您的脚本存在其他错误，导致 API 更新程序无法成功运行，控制台会显示一条消息来通知您。您必须先解决这些错误，然后 API 更新程序才能完成更新。

与 API Updater 相关的命令行参数

从命令行以批处理模式运行 Unity 时，请使用-accept-apiupdate选项来运行 API 更新程序。有关详细信息，请参阅命令行参数。

伐木

API 更新程序将其对任何程序集所做的更改记录到编辑器日志中。要控制记录的信息量，请将UNITY_APIUPDATER_LOG_THRESHOLD环境变量设置为所需的日志阈值并启动 Unity。例如：

在 Windows 上：

c:> set UNITY_APIUPDATER_LOG_THRESHOLD=Debug
c:> \path\to\unity\Unity.exe

在 Linux 上：

$ export UNITY_APIUPDATER_LOG_THRESHOLD=Debug
$ /path/to/unity/Unity

在 Mac 上：

$ export UNITY_APIUPDATER_LOG_THRESHOLD=Debug
$ /path/to/unity/Unity

注意：您也可以使用版本控制用于管理文件更改的系统。您可以将 Unity 与最常见的版本控制工具结合使用，包括 Perforce、Git、Mercurial 和 PlasticSCM。更多信息
请参阅术语表以查看 API 更新程序对项目脚本所做的更改。

AssemblyUpdater 完成后，Editor.log将显示更改。例如：

[AssemblyUpdater] Property access to 'UnityEngine.Rigidbody
UnityEngine.GameObject::get_rigidbody()' in 'System.Void
Test.ClassReferencingObsoleteUnityAPIThroughEditorAssembly::Run()' replaced with 'T
UnityEngine.GameObject::GetComponent<UnityEngine.Rigidbody>()'.

下表描述了UNITY_APIUPDATER_LOG_THRESHOLD环境变量：

故障 排除

API 更新失败。检查以前的控制台消息。

API 更新程序无法更新所有过时的代码。如果更新程序无法保存其更改，例如，如果用户对脚本具有只读权限，则可能会发生这种情况。

检查控制台中的前面几行，查看更新过程中发生的任何问题。