升级到 Unity 2019 LTS

Note: Follow the advice in this section in release order. For example, if you need to upgrade your project from 2020 to 2022, read the 2021 upgrade guides to see if there are any changes that you need to make before you read the 2022 upgrade guides.

本页面列出了从任何 Unity 2018 版本升级到 2019 LTS 时在 Unity 2019 版本中可能对现有项目造成影响的更改。如果要从 Unity 2017 版本升级，请首先参阅升级到 Unity 2018 LTS 指南。

请注意，2019 LTS 也称为 2019.4。

页面大纲

• 轻量级渲染管线 (LWRP) 变为通用渲染管线 (URP)
• ShaderUtil 更新
• 动画 C# 作业
• 可编程渲染管线 (SRP) API 更改
• 可寻址资源
• 新的资源导入管线
• Tilemap Editor 现在是一个包
• SpriteTooling 现在是一个包
• Unity UI 现在是一个包
• UI Elements 现在是标准功能，而非实验性功能
• .NET 3.5 Equivalent 脚本运行时已删除
• 光照改进
• UnityAPICompatibilityVersionAttribute 构造函数更改
• 更改的系统要求
• 多玩家 (UNet) 高级 API 已移入包中 *删除了 UNITY_ADS 编译器指令

---

轻量级渲染管线 (LWRP) 变为通用渲染管线 (URP)

现在，轻量级渲染管线 (LWRP) 在 Unity 2019.3 和更高版本中变为通用渲染管线 (URP)。

如果您的项目使用 LWRP，则需要升级项目以使用 URP。有关升级过程的逐步操作指南，请参阅 LWRP 到 URP 升级指南。

回到顶部

ShaderUtil 更新

ShaderUtil.ClearShaderErrors() 已替换为 ShaderUtil.ClearShaderMessages() 以确保命名一致性，现在已标记为“过时”。在 Unity 2019.4 中打开现有项目脚本时，它们会自动升级。

回到顶部

动画 C# 作业

动画 C# 作业已移出实验性命名空间（从 UnityEngine.Experimental.Animations 移至 UnityEngine.Animations）。

Unity 2019.4 自动更新您的大多数脚本，但具有以下 Animator 作业扩展方法的脚本除外：

• BindStreamTransform
• BindStreamProperty
• BindCustomStreamProperty
• BindSceneTransform
• BindSceneProperty
• OpenAnimationStream
• CloseAnimationStream
• ResolveAllStreamHandles
• ResolveAllSceneHandles

必须手动将 using UnityEngine.Animations; 语句添加到这些脚本。

回到顶部

可编程渲染管线 (SRP) API 更改

未记录在册的 RenderPipeline.beginCameraRendering 和 RenderPipeline.beginFrameRendering 事件已被删除。应该用 RenderPipelineManager 类中的事件替换这些事件。

RenderPipeline 静态保护的函数 BeginFrameRendering 和 BeginCameraRendering 已被删除。必须将这些函数替换为参数中接受 ScriptableRenderContext 的签名。另外，现在还必须调用 EndCameraRendering 和 EndFrameRendering 方法。

回到顶部

可寻址资源

现在已弃用 AsyncLoad。请改用 Async.LoadAssetAsync。

回到顶部

新的资源导入管线

新的资源导入管线可在 Unity 2019.3 及更高版本中使用。如果已有现成的项目，则可以使用 Editor 中的 __Project Settings 窗口__来升级到新的资源导入管线：

选择 Version 2 将告诉编辑器您现在要对该项目使用新的资源导入管线，然后重新启动您的项目就会使用新的资源导入管线代码将项目重新导入。从本质上讲，这一过程与删除 Library 文件夹具有相同的效果，但不会删除这个文件夹。切换为使用资源导入管线 V2 时，原始资源导入管线的导入结果不会被删除，因为 V2 会创建自己的文件夹结构来存储导入结果。 在 Unity 2019.2 或更早版本中创建的项目在默认情况下仍将使用原始资源导入管线。首次在 Unity 2019.3 中打开此类项目时，可以选择升级到新的资源导入管线。如果您拒绝这样做，则项目将继续使用原始的资源导入管线。此外，所选版本会存储在项目的 EditorSettings.asset 文件中，因此可以进行版本控制。

使用新资源导入管线创建的新项目

使用 Unity 2019.3 或更高版本创建新项目时，新的资源导入管线已成为新的默认工作方式。创建的所有新项目都将使用新管线。

新资源导入管线的行为变化

同一资源的多个版本缓存在 Library 文件夹中
在 Unity 2019.2 之前（具有原始的资源导入管线），Library 文件夹包含资源的 GUID 作为文件名。因此，从一个平台切换到另一个平台将使 Library 文件夹中的导入结果无效，从而导致每次切换平台时都要重新导入。

资源导入管线 V1

如果您每天必须在平台之间来回切换多次，这可能很容易就用去数小时时间，具体取决于您的项目规模。 一些开发者已经找到这个问题的解决方法，例如在计算机上按平台创建项目副本，但是这样做的扩展性不是很好。 在新的资源导入管线中，我们删除了 GUID 到文件名的映射。由于会跟踪特定资源的依赖关系，因此我们能够通过哈希算法将所有这些数据整合在一起，从而创建资源导入结果的修订版。这样，我们就可以对每个资源进行多次修订，意味着我们不再受限于 GUID 到文件名的映射。没有这样的要求后，我们可以拥有在不同配置之间都有效的导入结果。为了实现快速平台切换，我们可以为每个平台提供一个导入结果，因此，在来回切换平台时，导入结果便已经存在，这样可以使平台切换比使用资源导入管线 V1 快许多个数量级。

资源导入管线 V2

缓存和 Unity Accelerator
大多数导入器进行了大量改进工作，旨在改善它们的确定性并对缓存产生积极影响。这意味着，如果使用 Unity Accelerator，则导入结果将被上传到集中的存储位置，其他机器可以连接到该位置并因为同一资源在另一台机器上已经完成处理而受益。现在可以缓存具有动态依赖项的资源（例如，嵌套预制件、着色器等）。有关导入器及其关联文件的更全面列表，请查看新的 AssetDatabase 手册页

缓存脚本化导入器 (Scripted Importer)：
具有已注册依赖项的 ScriptedImporter 和导入器并未与旧的资源导入管线一起缓存。

以前的行为

With the old Asset Import Pipeline, the switching of platforms invalidated all imports as the Import Result was GUID based, thus switching a platform would overwrite the import result every time.

新的行为

In the new Asset Import Pipeline, switching platforms does not invalidate imports as the File on disk representing the import result is a hash of its own contents, thus ensuring that when switching platform the contents are different and result in a new file, thus keeping both versions of the Import Result around and simply switching between one or another, without having to import anything.

调用 OnPostProcessAllAssets 的次数

在旧的资源导入管线中，对 OnPostProcessAllAssets 函数的调用次数是不确定的。这意味着对于相同的更改，可以一次或多次调用此函数。新的资源导入管线中将对检测到的脚本更改（.cs 文件）进行一次 OnPostProcessAllAssets 调用，而对非脚本更改（如 .png、.fbx、.wav 文件）再进行一次调用。

同步脚本编译

在旧的资源导入管线中，可能会触发编译并在进行编译时使链条进入运行模式。在某些情况下，这可以节省大量时间，因为非同步编译可能导致不确定的结果。新的资源导入管线已对此进行了更改，由资源导入管线驱动脚本编译的大多数工作，因此现在需要确定性方法，从而锁定编辑器，直到脚本编译完成为止。

回到顶部

Tilemap Editor 现在是一个包

Tilemap Editor 现在是一个包。该包将自动安装在使用 2D 项目模板创建的新 Unity 项目中。有关安装包的更多信息，请参阅添加和删除包。

已将所有公共类移到 UnityEditor.Tilemaps 命名空间。Unity 将引用这些类的脚本编译到 “Unity.2D.Tilemap.Editor” 程序集定义资源中。它们如下：

• GridBrush
• GridBrushEditorBase
• GridBrushEditor
• GridSelection

Unity 将尝试在脚本中使用 using 语句来更新相关的瓦片地图，但是请检查并在必要时进行更改。

如果要使用属于程序集定义的脚本来引用瓦片地图工具类，应将“Unity.2D.Tilemap.Editor”程序集定义添加为程序集定义下的程序集定义引用。Unity 可能已经自动为您进行此设置，但如果尚未设置，请进行更改。

如果您预编译的程序集引用早期 Unity 版本的瓦片地图工具类，则由于这些更改，您在使用它们时会遇到问题。如果可能，请根据新的瓦片地图工具程序集来更新并重新编译这些程序集。

如果您预编译的程序集引用早期 Unity 版本的瓦片地图工具类，您需要更新并重新编译这些程序集以引用新的瓦片地图工具程序集。

导入预编译的程序集时，这些问题的示例如下（作为 Console 窗口中的错误）：

Failed to extract {Class in Precompiled Assembly} class of base type UnityEditor.GridBrush when inspecting {Precompiled Assembly} Unloading broken assembly {Precompiled Assembly}, this assembly can cause crashes in the runtime

这些错误可能是因为从某个瓦片地图工具类（例如 GridBrush）继承而引起的。

使用预编译的程序集时，这些问题的示例如下（作为 Console 窗口中的错误）：

TypeLoadException: Could not resolve type with token 01000011 (from typeref, class/assembly UnityEditor.GridBrush, UnityEditor, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null)
Error: Could not load signature of {Method in Precompiled Assembly) due to: Could not resolve type with token 01000011 (from typeref, class/assembly UnityEditor.GridBrush, UnityEditor, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null) assembly:UnityEditor, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null type:UnityEditor.GridBrush member:(null) signature:<none>

这些错误可能是因为创建或调用瓦片地图工具类（例如 GridBrush）的某个方法而引起的。

回到顶部

SpriteTooling 现在是一个包

Sprite Tooling (Sprite Editor Window) is now a package. For more information on installing a package see Adding and removing packages.

• 默认情况下未将此包添加到新的 Unity 项目中，除非新项目是使用 2D 项目模板创建的。
• 升级到 Unity 2019.1 后，此包会添加到预先存在的 Unity 项目（2019.1 及更早版本）中。如果您的项目没有使用 2D 精灵，并且不需要使用 Sprite Tooling，您可以删除此包。
• 作为将 Sprite Tooling 转换为包的一部分，已删除实验性名称空间。如果您的项目有脚本引用与 Sprite Tooling 相关的类，请确保升级后它们使用正确的命名空间，例如在必要时添加“using UnityEditor.U2D.Sprites”。
• 如果要使用属于程序集定义的脚本来引用精灵类，需要将“Unity.2D.Sprite.Editor”程序集定义添加为程序集定义下的程序集定义引用。

回到顶部

Unity UI 现在是一个包

Unity UI (UGUI) 现在是一个包 (com.unity.ugui)。可以从 Package Manager（菜单：Window > Package Manager）访问它。

Unity UI 是 Unity 随附的核心包。您无需将其安装在新项目中。 当您将使用 2019.2b1 和更早版本创建的现有 Unity 项目升级到 Unity 2019.2 时，会自动添加此包。 程序集定义会自动获得对 uGUI 程序集的引用。 如果在较旧的 Unity 版本之上安装 Unity 2019.2，请确保已删除 \Editor\Data\UnityExtensions\Unity 中的 GUISystem 文件夹。否则，您可能会收到类重新定义错误。 Unity UI 源代码不再发布到 BitBucket，因为 Unity 会随该包一起提供这些代码。 Unity UI API 文档不再出现在主要的脚本 API 参考中。您可以从 Unity UI 包文档的“脚本 API”部分访问它。

回到顶部

UI Elements 现在是标准功能，而非实验性功能

请参阅 UI Elements 2019.1 升级指南以了解更多信息。

回到顶部

.NET 3.5 Equivalent 脚本运行时已删除

已删除用于脚本运行时版本 (Scripting Runtime Version) 的 .NET 3.5 Equivalent 选项。在 2019.2 中打开项目时，项目会自动迁移以使用 .NET 4.x Equivalent 选项。

回到顶部

光照改进

在 2019.1 之前，Indirect Intensity 滑动条仅在使用渐进光照贴图 (Progressive Lightmapper) 时影响光照贴图。对于 Enlighten，该滑动条适用于光照探针和光照贴图。现在所有后端都会将 Indirect Intensity 值应用于光照贴图和光照探针。 再次对光照进行烘焙时，您可能会注意到，如果修改了 Indirect Intensity 值，探针会显得更亮。 在升级后，最好在重新烘焙光照贴图之前清除烘焙数据 (Clear Baked Data)。

回到顶部

UnityAPICompatibilityVersionAttribute 构造函数更改

接受单个字符串的构造函数现在已弃用。请参阅文档以了解关于支持的重载的信息。

回到顶部

更改的系统要求

以 Unity 2019 LTS 创建的项目需要 macOS 10.12 或 Ubuntu 16.04 或更高版本。

回到顶部

多玩家 (UNet) 高级 API 已移入包中

已将多玩家高级 API 从扩展移入到包中。这不会影响 NetworkTransport 类（低级 API）。已将 Unity 引擎中的所有依赖项移入到包中。这意味着高级 API 现在是独立的，只是目前无法迁移性能分析器中的某些挂钩。

包含高级 API 的更早项目将自动添加该包以防止编译器错误。新项目不会发生此情况，您可以根据需要从 Package Manager 窗口中添加该包。请参阅多玩家高级 API 文档。

回到顶部

删除了 UNITY_ADS 指令

截至 2019.4，Unity 没有自动定义 UNITY_ADS。您需要在脚本中停止使用 UNITY_ADS，或为其创建一个新的自定义全局 #define。有关如何创建新的自定义全局 #define 的指南，请参阅 Platform Dependent Compilation 页面。