API 更新程序

为了提高可用性和性能，Unity 可能会更改类、函数和属性（API）的工作方式。有时，这些改进在从一个主要 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 更新程序的工作流程：

Unity 触发脚本编译。
API 更新程序检查它可以处理的可更新编译器错误或警告。
- 如果它没有找到任何错误或警告，则流程结束。
- 如果它找到任何错误或警告，它会显示一个对话框，提供自动更新选项。
  在您允许 API 更新程序更新您的脚本或程序集之前，请关闭编辑器并备份您的项目。当您重新打开项目时，Unity 会编译您的脚本并触发 API 更新程序。
如果您接受更新，API 更新程序将更新同一编译单元中的所有脚本。
API 更新程序会重复此过程，直到它检测到不再有它可以处理的错误或警告。

如果包含过时代码的脚本属于不同的编译阶段（例如编辑器脚本），则更新程序可能会运行多次。

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

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

与 API 更新程序相关的命令行参数

当从命令行以批处理模式运行 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 更新程序无法应用特定更新时，会记录错误消息，这需要您采取纠正措施（通常是请求原始程序集作者提供程序集的更新版本）。
警告	API 更新程序记录警告和错误消息。当 API 更新程序应用用户可能需要查看的更改时，会记录警告消息。
信息	API 更新程序记录信息、警告和错误消息。信息消息包括 AssemblyUpdater 应用的更新。
调试	API 更新程序记录所有消息。这对于故障排除很有用，例如，如果您遇到与 API 更新程序相关的问题，并且想要向 Unity 报告这些问题。

故障排除

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

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

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

2018 年 7 月 31 日页面修订
在 Unity 2017.2 中添加了“accept-apiupdate”命令行选项
Unity 2018.3 中改进了 AssemblyUpdater 日志记录 NewIn20183

升级 Unity

升级到 Unity 6

Unity 手册