# 安全模式

> Understand Unity's Safe Mode, a mode that the Unity Editor enters if there are compilation errors in your project.

## 概述

Unity 的安全模式是在打开有脚本编译错误的项目时 Unity 编辑器可以进入的模式。安全模式旨在为解决编译错误提供最佳环境，以便可以快速将项目恢复到可运行的状态。

在安全模式下，Unity 提供编辑器用户界面的最小版本，功能有限。它只导入与脚本相关的资源，并阻止导入非脚本资源（例如模型、材质、纹理和预制件）。这是因为安全模式不适用于内容制作，仅用于解决编译错误。

安全模式绝不允许托管代码从项目或其包中运行。这意味着您自己的脚本（例如[编辑器脚本](/engine/6000.0/manual/working-in-unity/uitoolkits/guiscripting-guide/extending-the-editor.md)、[资源后处理器](/engine/6000.0/script-reference/unity-editor/asset-postprocessor.md)和[脚本导入器](/engine/6000.0/manual/working-in-unity/assets-and-media/asset-workflow/asset-types/scripted-importers.md)）无法运行。安全模式还会禁用[程序集覆盖](/engine/6000.0/manual/scripting/compilation-and-code-reload/script-compilation/assembly-definition-files/class-assembly-definition-importer.md#assembly-references)以及 [Burst](/engine/6000.0/manual/packages-list/packages-all/pack-safe/com-unity-burst.md) 和 [Roslyn](/engine/6000.0/manual/scripting/debugging-and-diagnostics/roslyn-analyzers.md) 分析器。这可确保处于安全模式的编辑器始终功能齐全且可靠，即使它在损坏严重的状态下打开项目也是如此。

当 Unity 检测到不再有编译错误时，它会自动退出安全模式。退出安全模式时，Unity 会完整导入项目，编辑器会恢复其正常的完整功能。

## 编译错误的常见原因

执行以下操作时，会发生一些可能导致遇到编译错误的常见情况：

* 将项目从较旧版本的 Unity 升级到较新版本。
* 在与创建项目时不同的 Unity 版本中打开项目。
* 打开缺失[包](/engine/6000.0/manual/packages-list.md)或包的版本不正确的项目。
* 在自己的脚本中打开有错误的项目。
* 在提取的最新更改包含编译错误的情况下，在[版本控制](/engine/6000.0/manual/unity-editor/editor-features/version-control.md)下打开项目。

在没有安全模式的情况下打开存在编译错误的项目可能会导致许多类型的问题。例如，项目中的[包](/engine/6000.0/manual/packages-list.md)可能无法正确加载或运行，并且资源可能错误地导入，从而导致[库](/engine/6000.0/manual/working-in-unity/assets-and-media/asset-workflow.md#processing)或[缓存服务器](/engine/6000.0/manual/working-in-unity/assets-and-media/unity-accelerator.md)中存在不正确的缓存工件。

在这些情况下，你通常不会希望在能够解决错误之前，还得等着项目的其余部分完成导入。安全模式提供了工具来供您自己解决这些脚本相关问题，或是使用版本控制将项目更新到解决了错误的较新版本，而无需等待项目完全导入。

## 进入安全模式

打开存在编译错误的项目时，编辑器会显示一个对话框，询问是否要进入安全模式：


**打开存在编译错误的项目时，Enter Safe Mode? 对话框会提示进入安全模式:**
![](/api/media?file=/engine/6000.0/media/images/SafeModeDialog.png)

此时有三种选择：

* **Enter Safe Mode（进入安全模式）**
* \*\*Ignore（忽略）\*\*错误并打开项目
* \*\*Quit（退出）\*\*Unity

在大多数情况下，应该选择 **Enter Safe Mode** 以解决项目中的错误（或者，如果在使用版本控制，则提取包含错误修复的更改）。安全模式可为解决编译错误提供最佳环境，以便在 Unity 导入项目的其余部分之前，可以快速将项目恢复到可运行的状态。

但是，在某些情况下可能不想进入安全模式，在这种情况下可以 \*\*Quit（退出）\*\*Unity，或 \*\*Ignore（忽略）\*\*错误。

**注意**：*可以在 ****Edit > Preferences > Asset Pipeline > Show Enter Safe Mode Dialog*** 中禁用此对话框*。如果禁用此对话框，则 Unity 在打开存在编译错误的项目时会自动进入安全模式。*

### 退出而不进入安全模式

安全模式专为修复编译错误而设计。如果作为团队的一部分在处理 Unity 项目，但是不对导致错误的脚本负责，并且不知道该怎么做，则应该在该对话框中选择 **Quit**，并联系团队中的程序员以寻求建议。

### 忽略错误并继续导入

在某些情况下不需要项目处于可用状态（例如，如果打开旧项目以复制某些部分，或者只是检查其配置方式）。在这种情况下，可以忽略错误并仍然在损坏的状态下打开项目。

如果选择 **Ignore**，并且以后要在安全模式下打开项目，则可以关闭并重新打开 Unity 以再次访问 "Enter Safe Mode" 对话框。

### 忽略编译错误的影响

如果选择忽略错误，则 Unity 会继续导入其余资源并完整打开项目。此处的潜在影响包括：

* 项目可能未处于可用状态。在错误解决之前，可能无法进入播放模式或创建项目的编译版本。此外，项目中的任何包都可能无法正确加载，或者根本无法加载。

* Unity 可能需要导入资源两次；一次是在启动时，另一次是在解决项目的编译错误后。这会增加在可用状态下加载项目所需的时间量。

* 如果项目使用[可编程渲染管线](/engine/6000.0/manual/rendering-and-post-processing/render-pipelines/scriptable-render-pipeline-introduction.md)，则渲染管线可能无法加载，从而导致视觉效果问题，如[错误着色器](/engine/6000.0/manual/materials-and-shaders/shaders/shader-troubleshooting/shader-error.md)效果。

* 脚本编译错误可能会导致项目中出现次要错误。例如，如果项目中的[脚本化导入器](/engine/6000.0/manual/working-in-unity/assets-and-media/asset-workflow/asset-types/scripted-importers.md)由于编译错误而无法加载，则资源可能在不正确的状态下导入。

安全模式旨在帮助避免所有这些问题。

## 安全模式下的编辑器

在安全模式下，Unity 提供功能有限的最小编辑器界面。


**安全模式下的编辑器:**
![](/api/media?file=/engine/6000.0/media/images/SafeModeEditor.png)

Unity 编辑器在编辑器顶部的工具栏部分显示一个安全模式横幅，它替代了标准编辑器工具栏。该工具栏指示处于安全模式，并提供 **Exit Safe Mode** 按钮，可用于忽略剩余错误并退出安全模式。该横幅还指示项目是否使用[预览包](/engine/6000.0/manual/packages-list/packages-all/pack-preview.md)。

Unity 编辑器在安全模式下保留[与代码编辑器的集成](/engine/6000.0/manual/scripting/environment-and-tools/ide-support.md)，因此可以双击脚本资源或[控制台错误](/engine/6000.0/manual/unity-editor/using-the-editor/console.md)[](/engine/6000.0/manual/unity-editor/using-the-editor/console.md)以打开关联脚本，并且可以通过 **Assets** 菜单打开 C# 项目。它还保留了与 [Version Control 系统](/engine/6000.0/manual/unity-editor/editor-features/version-control.md)的集成。

### 安全模式下的有限窗口集

编辑器在安全模式下显示有限的窗口选择。如下：

* Console 窗口
* Project 窗口
* Inspector 窗口
* Package Manager 窗口

这些是唯一可用的窗口，因为它们与修复编译错误相关。在安全模式下没有其他窗口可用。

### 安全模式下的编辑器菜单

在安全模式下，编辑器主菜单中的可用选项仅限于一组有限的选项。只能查看和选择与处理脚本相关的菜单选项；用于创建和处理其他内容的常规选项不可用。例如，无法创建或打开场景，或是创建非脚本资源（例如原始形状、光线或摄像机）。**GameObject** 和 **Component** 菜单不存在，而 **Window** 菜单仅提供一组有限的窗口。


**在安全模式下出现的有限编辑器菜单，其中显示用于创建资源的可用选项。:**
![](/api/media?file=/engine/6000.0/media/images/SafeModeLimitedMenu.png)

### 安全模式下的 Project 窗口

在安全模式下，Project 窗口与其在安全模式之外的正常行为相比有一些功能差异。

主要区别在于只能选择与编译相关的资源。其他资源类型不可选择。它们在 Project 窗口中保持显示为灰色，但无法选择或编辑它们。

具体来说，可以与之交互的编译相关资源类型有：

* C# 文件 (.cs)
* DLL 文件 (.dll)
* 程序集定义 (.asm)
* 响应文件 (.rsp)
* 规则集文件 (.ruleset)

此外，不可选择的资源的图标不会显示资源内容的预览。而是显示通用图标来表示资源的类型。


**Project 窗口对不可选择的资源显示通用图标。:**
![](/api/media?file=/engine/6000.0/media/images/SafeModeProjectWindow.png)

**创建 (+)** 菜单按钮处于禁用状态，并且 Project 窗口上下文菜单中的可用选项集会减少。


**项目窗口中的创建 (+) 菜单按钮在安全模式下处于禁用状态:**
![](/api/media?file=/engine/6000.0/media/images/SafeModeCreateButton.png)

## 退出安全模式

解决了所有编译错误后，Unity 会自动退出安全模式。Unity 随后会继续打开项目并导入资源。

要在仍然剩余编译错误时退出安全模式，请选择安全模式工具栏中的 **Exit Safe Mode** 按钮。不推荐这样做（请参阅[忽略编译错误的影响](/engine/6000.0/manual/unity-editor/editor-features/safe-mode.md#IgnoringErrors)），Unity 会通过一个对话框提示确认决策。


**Safe Mode 工具栏中的 Exit Safe Mode 按钮:**
![](/api/media?file=/engine/6000.0/media/images/SafeModeExitButton.png)

如果在项目中仍然存在错误时退出安全模式，并且以后要返回安全模式，则可以关闭并重新打开 Unity 以再次访问 "Enter Safe Mode" 对话框。

## 批处理模式下的安全模式

在批处理模式下，如果项目中存在编译错误，Unity 会自动退出，除非使用 `-ignoreCompilerErrors` [命令行参数](/engine/6000.0/manual/unity-editor/editor-features/command-line-arguments.md)。