此页面列出了 Unity 6 中的更改，这些更改可能会在您从 2022 LTS 版本升级到 Unity 6 时影响现有项目。
此升级指南介绍了如何升级到 Unity 内置渲染管线的 Unity 6 版本。要升级其他渲染管线，请参阅
要升级其他包，请参阅您正在使用的包的文档。
在 渐进式光照贴图器 的高级过滤选项（照明窗口 > 光照贴图设置 > 过滤 > 直接过滤 > Gaussian）中，包括一个 Gaussian 选项。现在，Gaussian 过滤的半径控制支持小数增量，例如 0.5。以前，此控制仅支持整数步长（1 到 5）。
由于此更改，这些属性现在在 C# API 中已弃用
int LightingSettings.filteringGaussRadiusAOint LightingSettings.filteringGaussRadiusDirectint LightingSettings.filteringGaussRadiusIndirect弃用属性的浮点替换为
float LightingSettings.filteringGaussianRadiusAOfloat LightingSettings.filteringGaussianRadiusDirectfloat LightingSettings.filteringGaussianRadiusIndirect您可以调用其中一个已弃用的成员函数，将 Gaussian 滤波器半径四舍五入到最接近的整数。
光探测器现在与 光照贴图预渲染的纹理，其中包含光源对场景中静态物体的影响。光照贴图叠加在场景几何体之上，以创建照明效果。 更多信息
在 术语表 中查看 一样明亮。以前，Unity 的 光探测器光探测器存储有关光线如何穿过场景中空间的信息。在一个给定空间内排列的光探测器集合可以改善该空间内移动物体和静态 LOD 景点的照明。 更多信息
在 术语表 中查看 仅为其应有亮度的 94%。因此，使用光探测器照明的物体看起来比使用光照贴图照明的物体稍暗。由于此更改的微妙性，许多用户可能不会看到明显的差异。
如果您更喜欢旧的外观，可以使用以下方法实现它
Enlighten 烘焙 全局照明一组技术，用于模拟直接和间接照明，以提供逼真的照明效果。
在 术语表 中查看 光照贴图后端不再可用。
将项目升级到此版本时，Unity 会从光照贴图器选择下拉菜单中删除 Enlighten 烘焙后端，并在您选择 Enlighten 烘焙后端的所有场景中替换为渐进式光照贴图器。
在 Apple 硅设备上，Unity 会用渐进式 GPU 光照贴图器替换 Enlighten 烘焙后端。在所有其他设备上，Unity 会选择 CPU 渐进式光照贴图器。
Enlighten 预计算的实时全局照明仍然可用，并且在 Unity 2024 LTS 之前一直受支持。
UnityPlayer Java 类已被两个新的桥接类 UnityPlayerForActivityOrService 和 UnityPlayerForGameActivity 替换。这两个新类都派生自 UnityPlayer，但公共方法（例如 displayChanged 和 windowFocusChanged）已从 UnityPlayer 特别移动到 UnityPlayerForActivityOrService。
如果您 扩展默认的 Unity 活动 并使用 UnityPlayer 类，您可能会遇到编译错误。在这种情况下，将 UnityPlayer 重命名为 UnityPlayerForActivityOrService。
UnityPlayer Java 类不再扩展 FrameLayout。如果您需要访问 FrameLayout，请在 UnityPlayer 实例上调用 getFrameLayout 函数。
RenderPipelineEditorUtility.FetchFirstCompatibleTypeUsingScriptableRenderPipelineExtension 现在已弃用。请改用 GetDerivedTypesSupportedOnCurrentPipeline。此方法的签名也不同；现在它返回所有派生类型，而不仅仅是遇到的第一个类型。这可以防止出现不一致，因为 Unity 不保证类型顺序。
CustomEditorForRenderPipelineAttribute 和 VolumeComponentMenuForRenderPipelineAttribute 现在已弃用。请改用 CustomEditor 和 VolumeComponentMenu。要限制这些属性激活时管线的选择，请将它们与 SupportedOnRenderPipelineAttribute 结合使用，并指定 RenderPipelineAsset 类型。如果您想激活与内置渲染管线一起工作的 SRP 属性，请使用 SupportedOnRenderPipelineAttribute 而不带参数。这在需要在特定管线上激活这些属性时，为两种属性提供统一的工作流程。
引入了修改 Android Gradle一个 Android 构建系统，可自动执行多个构建过程。此自动化意味着许多常见的构建错误不太可能发生。 更多信息
在 术语表 中查看 项目的新 API。此 API 可用于替换旧的 Android Gradle 模板工作流程。如果未使用新 API，模板仍然可以像以前一样工作。
要使用新 API，可以使用 模板升级器
Unity 的渐进式光照贴图器不再默认烘焙环境探测器和 天空盒一种特殊的材质，用于表示天空。通常是六面的。 更多信息
在 术语表 中查看 反射探测器一个渲染组件，它捕获其周围环境在所有方向上的球形视图，有点像相机。捕获的图像然后存储为 Cubemap，可供具有反射材质的物体使用。 更多信息
在 术语表 中查看，并且照明窗口中的重新计算环境照明设置已被删除。
为了避免新创建的场景没有环境照明，Unity 会分配一个包含环境照明的默认 照明数据资源，该环境照明与默认天空盒材质匹配。
在以下情况下，您必须在照明窗口中选择生成照明
如果您依赖以前的自动烘焙行为，但您使用默认的环境照明设置，Unity 会将场景升级为使用默认照明数据资源。
照明窗口中的自动生成设置已被删除，相关 API 现在已过时。
要为场景生成烘焙照明，您可以执行以下任一操作
Lightmapping.Bake API。Lightmapping.BakeAsync API。要在编辑时检查光照贴图，您现在可以选择一个 场景视图绘制模式 并将照明数据设置为预览。这将显示烘焙照明的预览。预览光照贴图是非破坏性的，您可以在烘焙场景后使用它们。
如果场景依赖于自动生成的照明，它将不再具有其烘焙照明。在照明窗口中选择生成照明以手动重新烘焙照明。
如果使用脚本打开场景，您现在必须使用 Lightmapping.Bake 或 Lightmapping.BakeAsync，而不是等待自动生成的照明完成。
以下图形格式在 2022.1 中先前已弃用，现在已过时，如果您使用它们，将产生编译错误
GraphicsFormat.DepthAutoGraphicsFormat.ShadowAutoGraphicsFormat.VideoAutoThe GraphicsFormatUtility.GetGraphicsFormat API 不再返回过时的格式。相反，它会执行以下操作
RenderTextureFormat.Depth 转换为 GraphicsFormat.None，而不是 GraphicsFormat.DepthAuto。GraphicsFormat.None 表示仅深度渲染。RenderTextureFormat.Shadowmap 转换为 GraphicsFormat.None，而不是 GraphicsFormat.ShadowAuto。如果您创建一个具有 GraphicsFormat.None 格式的 渲染纹理在运行时创建和更新的一种特殊类型的纹理。要使用它们，首先创建一个新的渲染纹理，并指定您的相机之一来渲染到其中。然后，您可以在材质中像使用普通纹理一样使用渲染纹理。 更多信息由于 GraphicsFormat.DepthAuto 和 GraphicsFormat.ShadowAuto 都被认为是深度模板格式，但用作颜色格式，因此您可能需要调整代码。
例如，在以下代码片段中，GraphicsFormatUtility.IsDepthFormat 返回 false 而不是 true
RenderTextureDescriptor desc = new RenderTextureDescriptor(256, 256, RenderTextureFormat.Depth, 32);
bool isDepthOnly = GraphicsFormatUtility.IsDepthFormat(desc.graphicsFormat);
要检查 RenderTexture 或 RenderTextureDescriptor 是否为仅深度，请使用以下方法之一
if (renderTexture.graphicsFormat == GraphicsFormat.None && renderTexture.depthStencilFormat != GraphicsFormat.None)if (renderTexture.format == RenderTextureFormat.Depth || renderTexture.format == RenderTextureFormat.Shadowmap)在运行时创建的 2D 纹理默认情况下不再限制其mipmap 上传。以前，必须通过 Texture2D 构造函数（在使用 TextureFormat 调用构造函数时提供 ignoreMipmapLimit 布尔参数，或在使用 GraphicsFormat 调用构造函数时提供 IgnoreMipmapLimit TextureCreationFlag），或通过切换已构建纹理的 tex.ignoreMipmapLimit 来显式禁用 mipmap 限制。此行为已更改：mipmap 限制现在是运行时创建的 2D 纹理的可选功能。
在不进行项目更改的情况下，在以下情况下，用户会错过 GPU 带宽和内存优化，并且可能会看到比预期更好的质量，因为纹理现在以全分辨率上传
在以下情况下，用户不会受到此更改的影响
ignoreMipmapLimit 为 false，tex.ignoreMipmapLimit 设置为 false。如果这些用户使用已弃用的构造函数，他们可能需要升级他们的 脚本一段代码，允许您创建自己的组件、触发游戏事件、随着时间的推移修改组件属性以及以您喜欢的任何方式响应用户输入。 更多信息
查看 术语表。
要升级您的脚本，请使用带有 MipmapLimitDescriptor 的 Texture2D 构造函数，以指示运行时纹理应受质量设置影响。
进行此更改是为了与 Texture2DArrays 的新 mipmap 限制支持保持一致。与其让每个纹理形状定义自己的默认 mipmap 限制行为，我们选择一致性，并决定运行时纹理应显式启用 mipmap 限制。此可选行为优于不可选行为，因为运行时纹理通常以更通用的方式使用，其中意外上传的 mip 比预期的少可能会比意外上传的 mip 多造成更大的危害。
简化了使用 UXML 在 UI(用户界面) 允许用户与您的应用程序交互。Unity 目前支持三种 UI 系统。 更多信息
查看 术语表 工具包中创建自定义控件的过程，以加快工作流程并使其更直观。
一项重要的改进是引入了 UxmlElement 和 UxmlAttribute 属性。这些属性简化了属性创作，并自动从属性名称派生属性名称，从而消除了对 UxmlTraits 和 UxmlFactory 类的需求。
您现在可以为特定数据类型创建自定义属性转换器，确保将值无缝地转换为 UXML 属性字符串以及从 UXML 属性字符串转换回来。我们还增强了 UxmlObjects，允许在 可视元素可视树的一个节点，它实例化或派生自 C# VisualElement 类。您可以设置外观、定义行为，并将其作为 UI 的一部分显示在屏幕上。 更多信息
查看 术语表 中定义自定义的非可视元素。新系统利用了 Unity 序列化，并使用源代码生成器为每个自定义元素类的所有 UxmlAttribute 定义的元素创建 UxmlSerializedData 类，从而支持自定义的 属性绘制器Unity 的一项功能，允许您通过在脚本上使用属性，或通过控制特定可序列化类的外观来自定义检查器窗口中某些控件的外观。 更多信息
查看 术语表、装饰器和各种属性。
引入“属性覆盖”功能使您能够自定义 UXML 属性的行为，并在您使用继承属性时提供灵活性。这些改进为在 Unity 2023.2 及更高版本中创建复杂的 UI 元素提供了更高效、更友好的体验。
例如，以下代码示例是一个使用 UxmlFactory 和 UxmlTraits 创建的自定义控件
public class HealthBar : VisualElement
{
private const float k_LowValue = 0;
private const float k_HighValue = 100;
// Declare as usable with Uxml
public new class UxmlFactory : UxmlFactory<HealthBar, UxmlTraits> { }
// Define attributes (and connect with class properties) for Uxml
public new class UxmlTraits : BindableElement.UxmlTraits
{
UxmlColorAttributeDescription m_Color = new UxmlColorAttributeDescription { name = "color", defaultValue = Color.white };
UxmlFloatAttributeDescription m_Value = new UxmlFloatAttributeDescription { name = "value", defaultValue = k_HighValue };
public override void Init(VisualElement ve, IUxmlAttributes bag, CreationContext cc)
{
base.Init(ve, bag, cc);
var bar = ve as HealthBar;
bar.color = m_Color.GetValueFromBag(bag, cc);
bar.value = m_Value.GetValueFromBag(bag, cc);
}
}
public Color color { get; set; }
[Range(k_LowValue, k_HighValue)]
public float value { get; set; }
}
以下代码示例与前面的代码示例执行相同操作，但使用新的 UxmlElement 和 UxmlAttributes 系统
[UxmlElement]
public class HealthBar2 : VisualElement
{
private const float k_LowValue = 0;
private const float k_HighValue = 100;
[UxmlAttribute]
public Color color { get; set; } = Color.white;
[UxmlAttribute]
[Range(k_LowValue, k_HighValue)]
public float value { get; set; } = k_HighValue;
}
有关更多示例和信息，请参阅 Unity UI Toolkit 文档，并关注今年秋天发布的深入博客文章。
Assets/Create 菜单已重新组织并进行分类。作为这次大修的一部分，Unity 内置 ScriptTemplate 文件已重命名。
使用 CreateAssetMenuAttribute、MenuItemAttribute 或自定义 ScriptTemplate 向 Assets/Create 菜单添加元素的用户可能需要更改其菜单项的优先级，因为其相对于其他元素的位置现在有所不同。
通过使用 EditorApplication.ExecuteMenuItem API 执行这些菜单项来创建资产的用户必须验证菜单项的新路径。
以前覆盖 Unity 内置 ScriptTemplate 的用户必须更新其覆盖文件的名称，以确保它们与内置模板的新名称匹配。
ExecuteDefaultAction 和 ExecuteDefaultActionAtTarget 方法已弃用。已添加以下方法来替换它们
HandleEventTrickleDownHandleEventBubbleUpUnity 在事件分发路径中的每个元素上执行这些新方法，紧接在该元素的 TrickleDown 和 BubbleUp 回调之后。在这些方法期间，分发阶段分别设置为 TrickleDown 或 BubbleUp，并且事件的 currentTarget 与执行方法的元素一致。
AtTarget 分发阶段和 PreventDefault 方法已弃用。现在，调用 StopPropagation 或 StopPropagationImmediately 会同时停止进一步执行 HandleEventTrickleDown 和 HandleEventBubbleUp，以及停止进一步调用 TrickleDown 和 BubbleUp 回调。
在大多数情况下，如果您不升级到新方法，您的代码的行为不应发生重大变化。UI Tookkit 仍然按照以前的顺序调用已弃用的方法，或进行最小的调整。但是，UI Toolkit 中的所有标准控件都已迁移到使用新方法，相应地调整了其逻辑执行顺序。将已弃用的方法调用与升级控件的用法混合使用可能会导致某些逻辑与之前的 Unity 版本相比不同步。
要将现有代码升级到新方法，请执行以下操作
ExecuteDefaultAction 和 ExecuteDefaultActionAtTarget 替换为 HandleEventBubbleUp，将 PreventDefault 替换为 StopPropagation（或者如果 StopPropagation 已在同一代码块中调用，则删除对 PreventDefault 的调用。这涵盖了大多数情况）。BubbleUp 回调期间调用 PreventDefault 时遇到问题，而这在现在不再可能，并且无法通过 StopPropagation 替换，因为事件已到达其目标，请考虑在 TrickleDown 阶段添加回调以调用 StopPropagation。此步骤通常足以解决此类情况。Unity 着色器在 GPU 上运行的程序。 更多信息
查看 术语表 到 Metal 着色器的交叉编译在缓冲区布局方面有所改变。任何包含 min16float、half 或 real 类型的缓冲区现在与之前的 Unity 版本相比具有不同的内存布局。
如果您要针对 Metal 并且使用直接将原始数据写入缓冲区的 API，例如，您需要采取行动
如果您只使用 CommandBuffer.SetComputeFloatParam 或 Material.SetFloat，则无需采取行动。
更具体地说，缓冲区内的 HLSL min16float、half 和 real 始终转换为 32 位 MSL float，而在之前的 Unity 版本中，它们可能会转换为 16 位 MSL half，具体取决于目标平台。
如果您只在 Metal 平台上测试过着色器，请检查生成的 MSL 代码中的缓冲区，以确保布局与在 C# 中访问的缓冲区数据匹配。您可以通过在着色器代码中添加 #pragma metal_fxc_allow_float16_in_cpu_visible_buffers 并查看是否修复了任何视觉伪影来测试此更改是否会影响您的着色器。如果您注意到差异，请删除此 pragma，并调整您的着色器和 C# 代码，使其在没有 pragma 的情况下正常工作，以提高项目的跨平台兼容性。
要在缓冲区中使用本机 16 位浮点数，请考虑使用 DXC HLSL 编译器并在着色器中添加 #pragma require Native16Bit。但请注意，在 Unity 中使用 DXC 仍处于实验阶段。
全局包缓存 包含多个子文件夹。其中一个子文件夹 packages 已不再被 Package Manager 使用。
如果您有直接与全局包缓存的 packages 子文件夹交互的自动化脚本或管道，例如，如果您使用 UPM_CACHE_PATH 环境变量，则需要采取行动。如果是这种情况，您可以删除引用。Unity 不会提供 packages 的直接替换子文件夹。现在，包会直接解压缩到项目缓存中。
如果您不再维护使用 Unity 2023.2 创建的项目，则可以安全地从全局包缓存根目录中删除 packages 子目录。此操作是可选的。
以前的 Unity 编辑器版本支持使用 UPM_CACHE_PATH 环境变量来指定您想要 Package Manager 存储包压缩包的未压缩内容的位置的绝对路径。
只有当您拥有在UPM_CACHE_PATH中设置路径值的自动化脚本或管道时，您才需要采取行动。由于包现在直接提取到项目缓存中，因此没有UPM_CACHE_PATH的替代方案。但是，如果您以前使用过UPM_CACHE_PATH，您现在可以使用UPM_CACHE_ROOT环境变量，它设置全局缓存的根目录。请注意，全局缓存根目录是以前与UPM_CACHE_PATH关联的子文件夹的父目录。
有关更多信息，请参阅自定义全局缓存。
Unity 已更新 Android 使用的以下工具的默认版本。NDK、SDK 命令行工具和 SDK 工具的默认版本保持不变。更新的版本如下：
| 工具 | 版本 |
|---|---|
| Gradle | 8.4 |
| Android Gradle 插件 | 8.3.0 |
| SDK 构建工具 | 34.0.0 |
| SDK 平台工具 | 34.0.5 |
| Java 开发工具包 (JDK) | 17 |
如果您的项目使用自定义 Gradle 模板，请考虑重新创建这些模板，以避免与更新的 Android Gradle 插件版本出现任何构建问题。有关更多信息，请参阅使用 Gradle 模板文件修改 Gradle 项目文件。
之前的 Unity 编辑器版本包含一个支持 zstandard 压缩一种存储数据的方法，可减少其所需的存储空间。请参阅纹理压缩、动画压缩、音频压缩、构建压缩。
请参阅词汇表的 7-Zip 分支。
Windows 版本包含7-Zip-zstd，它是mcmilk/7-Zip-zstd 的分支，而mcmilk/7-Zip-zstd 又是上游 7-Zip 版本 22.01 的分支。此代码容易受到若干已知安全问题的攻击，例如CVE–2023–31102 和CVE–2023–40481。
macOS 和 Linux 版本包含p7zip-zstd，它是tehmul/p7zip-zstd（于 2017 年弃用）的分支，而tehmul/p7zip-zstd 又是p7zip（于 2016 年弃用）的分支，而p7zip 又是上游 7-Zip 的分支。此代码容易受到若干已知安全问题的攻击，例如CVE–2016–7804、CVE–2017–17969、CVE–2018–10115、CVE–2018–10172、CVE–2018–5996、CVE–2023–31102 和CVE–2023–40481。
Unity 6 包含适用于 Windows、macOS 和 Linux 编辑器的 7-Zip 正规上游版本 23.01。但是，此 7-Zip 上游版本不支持 .zip 或 .7z 档案的 zstandard 压缩或解压缩。它还缺少在mcmilk/7-Zip-zstd 分支中添加的额外压缩格式和哈希算法的支持。
如果您拥有使用对使用 zstandard 压缩的档案进行操作的 7za 或 7z.exe 二进制文件的包，请使用以下选项之一：