脚本
调试和诊断
在 Unity 中调试 C# 代码

调试和诊断

Debug 类

在 Unity 中调试 C# 代码

您可以使用调试器在应用程序运行时检查源代码。Unity 支持以下代码编辑器来调试 C# 代码：

Visual Studio（包含 Visual Studio Tools for Unity 插件）
Visual Studio 代码（具有 Unity for Visual Studio Code Extension）
Jetbrains Rider

尽管这些代码编辑器所支持的调试器特性略有不同，但它们都提供了一些基本功能，比如断点、单步执行和变量检查。您可以将这些代码编辑器附加到 Unity 编辑器或 Unity 播放器来调试代码。

Unity 中的托管代码调试可以在除 Web 之外的所有平台上运行。使用 Mono 和 IL2CPP 脚本后端都是可以的。

配置 IDE

有关配置每个受支持的 IDE 以便在 Unity 中进行调试的要求，请参阅集成开发环境 (IDE) 支持。

断点

使用断点可在代码中指定要暂停其执行的点。在外部代码编辑器中，可在想要调试器停止的代码行上设置断点。当代码编辑器处于断点时，您可以逐步查看变量的内容。

如果将代码编辑器附加到 Unity 编辑器（请参阅将代码编辑器附加到 Unity 编辑器），则在代码编辑器中选择“继续”选项或停止调试模式之前，Unity 编辑器将会处于无响应状态。

要了解如何在 Visual Studio 中设置断点，请参阅在 Visual Studio 中设置断点。

在 Unity 编辑器中调试

当 Unity Editor 处于运行模式时，可以调试在 Unity Editor 中运行的 C# 代码。

要在编辑器中进行调试，您需要将编辑器的代码优化模式设置为调试模式 (Debug Mode)，然后您可以附加具有调试功能的代码编辑器。

要更改代码优化模式，请选择 Unity Editor 状态栏右下角的调试 (Debug) 按钮。

Unity 的代码优化设置有两种模式：

Debug Mode，您可以使用该模式附加外部调试器软件，但在编辑器中以运行模式运行项目时会导致 C# 性能下降。
Release Mode，您可以以较高的 C# 性能在编辑器中以运行模式运行项目，但无法附加外部调试器软件。

当您单击状态栏中的调试 (Debug) 按钮时，会打开一个小弹出窗口，其中包含一个可用于切换模式的按钮。该窗口还显示有关当前模式的信息，并描述切换模式时会发生什么。

要更改 Unity 编辑器的启动模式，请选择编辑 (Edit)（macOS：Unity）> 偏好 (Preferences) > 常规 (General) > 启动时代码优化 (Code Optimization On Startup)。

在偏好 (Preferences) 中，您可以更改 Unity 启动时的代码优化模式。

要借用脚本来控制这些设置，请使用以下 API：

您还可以覆盖编辑器启动时的模式，或关闭调试器侦听套接字。为此，当您启动编辑器时请使用以下命令行参数：

-releaseCodeOptimization以发布 (Release) 代码优化模式启动 Editor。
-debugCodeOptimization以调试 (Debug) 代码优化模式启动编辑器。
-disableManagedDebugger在禁用调试器侦听套接字的情况下启动编辑器。

将代码编辑器连接到 Unity 编辑器

将代码编辑器附加到 Unity 编辑器的方式取决于所使用的代码编辑器，通常与代码编辑器的正常调试过程不同。某些代码编辑器支持选择要调试的 Unity 实例。有关专门针对代码编辑器的说明，请参阅代码编辑器外部文档。要了解如何在 Visual Studio 中执行此操作，请参阅附加 Visual Studio 到 Unity 编辑器。

将代码编辑器附加到 Unity 编辑器并准确调试时，回到 Unity 编辑器并进入运行模式。

Unity 播放器中的调试

要编译 Unity 播放器以供调试：

转到文件 (File) > 构建配置文件 (Build Profiles)。
在构建播放器之前启用开发构建 (Development Build) 和脚本调试 (Script Debugging) 选项。您还可以启用等待托管调试器 (Wait For Managed Debugger) 选项可使播放器等待调试器连接之后再执行脚本代码。
选择构建并运行 (Build And Run)。

将代码编辑器附加到 Unity 播放器

要在代码编辑器中将代码编辑器附加到 Unity 播放器，请选择播放器的 IP 地址（或机器名称）和端口。有关在 Visual Studio 中查找此属性的示例，请参阅将 Visual Studio 附加到 Unity 编辑器。

注意：代码编辑器将显示所有可供调试的 Unity 实例。请确保将代码编辑器连接到 Unity 播放器的正确实例，而不是连接到 Unity 编辑器（如果两者都在运行）。

连接调试器后，可以开始正常调试。有关如何将 Unity 播放器附加到特定代码编辑器的说明，请参阅代码编辑器外部文档。有关如何将移动设备上运行的 Unity 播放器附加到 Visual Studio 的示例，请参阅使用 Visual Studio 调试 Android 和 iOS 设备。

在 Visual Studio 中设置断点

如要在 Visual Studio 中设置断点，请在想要停止调试器的代码行位置，单击代码左侧的列。行号旁边会出现一个红色的圆，并会高亮显示这一行。

将 Visual Studio 附加到 Unity 编辑器

要将 Unity 编辑器附加到 Visual Studio 脚本，请打开 Visual Studio，转到调试 (Debug) > 附加 Unity 调试器 (Attach Unity Debugger)，然后选择要调试的 Unity 编辑器实例。

在以下示例图像中，有一个 Unity 实例在 Editor 中运行，还有一个 Unity 实例作为 Android Player 运行

使用 Visual Studio 调试 Android 和 iOS 设备

Android

调试 Android 设备上运行的 Unity Player 时，请通过 USB 或 TCP 连接到设备。例如，要在 Visual Studio 中连接到 Android 设备，请选择调试 (Debug) > 附加 Unity 调试器 (Attach Unity Debugger) 选项。此时会显示运行播放器实例的设备列表：

在此示例下，Android 设备通过使用 USB 和 Wi-Fi 连接到与运行 Unity 编辑器和 Visual Studio 的工作站所在的相同网络中。

iOS

如要调试 iOS 设备上运行的 Unity 播放器，请使用 TCP 连接到设备。例如，要在 Visual Studio (Mac) 中连接到 iOS 设备，请选择调试 (Debug) > 附加 Unity 调试器 (Attach Unity Debugger)。此时会显示运行播放器实例的设备列表：

确保设备只有一个有效网络接口（建议使用 Wi-Fi，关闭蜂窝数据），并确保 IDE 与设备之间没有防火墙阻止 TCP 端口（上面截屏中端口号为 56000）。

重要提示：iOS 不支持通过 USB 进行调试。

调试器故障排除

调试器出现的大多数问题都是由于代码编辑器无法找到 Unity 编辑器或 Unity 播放器。这意味着 Unity 编辑器或播放器无法正确附加调试器。因为调试器通过 TCP 连接到编辑器或播放器，所以连接问题通常是由网络造成的。可以采取下面几个步骤来对基本连接问题进行故障排除。

确保将调试器连接到正确的 Unity 实例

可以将代码编辑器连接到本地网络上已启用调试的任何 Unity 编辑器或 Unity 播放器的实例。在附加调试器时，确保将其附加到正确的 Unity 实例。如果您知道运行 Unity 播放器的设备的 IP 地址或计算机名称，这将有助于找到正确的实例。

验证与 Unity 实例的网络连接

代码编辑器在查找要调试的 Unity 实例时使用与 Unity 性能分析器相同的机制。如果代码编辑器找不到其应该找到的 Unity 实例，请尝试将 Unity 性能分析器连接到该实例。如果 Unity 性能分析器也找不到 Unity 实例，可能是运行代码编辑器或 Unity 实例的计算机上有防火墙。如果已设置防火墙，请参阅检查防火墙设置。

确保设备仅有一个激活的网络接口

许多设备有多个网络接口。例如，手机可以同时激活了蜂窝连接和 Wi-Fi 连接。为了通过使用 TCP 正确地将调试器连接到 Unity 实例，IDE 需要与设备上的正确接口建立网络连接。例如，如果您计划通过 Wi-Fi 进行调试，请确保将设备置于飞行模式以禁用所有其他接口，然后启用 Wi-Fi。

可以通过查看播放器日志来确定 Unity 播放器要求 IDE 使用的 IP 地址。查找日志中如下所示的部分：

Multi-casting "[IP] 10.0.1.152 [Port] 55000 [Flags] 3 [Guid] 2575380029 [EditorId] 4264788666 [Version] 1048832 [Id] iPhonePlayer(Example-iPhone):56000 [Debug] 1 [PackageName] iPhonePlayer" to [225.0.0.222:54997]...

此消息表明 IDE 将尝试使用 IP 地址 10.0.1.152 和端口 56000 来连接到设备。运行 IDE 的计算机必须能访问此 IP 地址和端口。

检查防火墙设置

Unity 实例通过使用 TCP 连接与代码编辑器进行通信。在大多数 Unity 平台上，都是在任选的端口上进行这种 TCP 连接。通常，您无需知晓该端口，因为代码编辑器应该能自动检测到这个端口。如果没有检测到，请使用网络分析工具来确定在运行代码编辑器的计算机上或者在运行 Unity 实例的计算机或设备上，哪些端口可能被阻止。找到这些端口后，请确保防火墙允许访问运行代码编辑器的机器上的端口和运行 Unity 实例的机器上的端口。

验证托管调试信息是否可用

如果调试器已经附加到 Unity 实例，但断点未加载，表示调试器可能无法找到代码的托管调试信息。托管代码调试信息存储在磁盘上托管程序集（.dll 文件）旁边名为 .pdb 的文件中。

如果启用了正确的偏好设置和构建选项（请参阅配置代码编辑器），Unity 会自动生成此调试信息。但是，Unity 不能为项目中的托管插件生成调试信息。如果关联的 .pdb 文件位于磁盘上 Unity 项目托管插件的旁边，则仅可从托管插件中调试代码。

防止设备锁定

对用于调试应用程序的设备禁用任何屏幕锁定。屏幕锁会导致调试器断开连接，并阻止其重新连接。在托管代码调试期间不要锁定屏幕。如果屏幕已经锁定，在设备上重新启动应用程序，以便调试器可以再次连接。

调试器导致的内存和线程泄漏

托管调试器在实现过程中，为了处理一些与线程启动和关闭相关的竞争条件，会泄漏一些操作系统级别的线程句柄和少量内存。在实际应用中，这种泄漏量通常较小，一般不会对应用程序的资源使用造成影响。当频繁创建和销毁大量线程时，这些泄漏就会变得明显。此外，这种特性也会给追踪真正的内存泄漏带来困难。因此，我们建议在排查内存泄漏问题时，禁用脚本调试功能。

代码编辑器外部文档

Visual Studio - 使用 Visual Studio Tools for Unity (Windows)
Visual Studio Code - Unity Development with VS Code
Jetbrains Rider - 调试 Unity 应用程序

其他资源

集成开发环境 (IDE) 支持