在Unity中调试C#代码

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

• Visual Studio（带有Unity工具集插件）
• Visual Studio for Mac
• JetBrains Rider

请注意，虽然Visual Studio IDE支持Unity调试，但Visual Studio Code文本编辑器则不支持。

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

Unity中的托管代码调试适用于所有平台，除了WebGL一个JavaScript API，用于在浏览器中渲染2D和3D图形。Unity WebGL构建选项允许Unity将内容发布为JavaScript程序，这些程序使用HTML5技术，并且使用WebGL渲染API在浏览器中运行Unity内容。 更多信息
在术语表中查看。它与MonoUnity中使用的脚本后端。 更多信息
在术语表中查看和IL2CPP一个Unity开发的脚本后端，您可以在构建某些平台的项目时将其用作Mono的替代品。 更多信息
在术语表中查看 脚本后端支持Unity中脚本的一个框架。Unity根据目标平台支持三种不同的脚本后端：Mono、.NET和IL2CPP。然而，通用Windows平台仅支持两个：.NET和IL2CPP。 更多信息
在术语表中查看脚本后端一起工作。

配置代码编辑器

Visual Studio（Windows）

Unity编辑器安装程序包括安装带有Unity工具集插件 插件在Unity外部创建的一系列代码，用于在Unity中创建功能。在Unity中可以使用两种类型的插件：托管插件（使用Visual Studio等工具创建的托管.NET程序集）和原生插件（特定平台的本地代码库）。 更多信息
在术语表中查看的Visual Studio选项。这是设置Visual Studio进行Unity调试的建议方法。

如果您的计算机上已经安装了Visual Studio，请打开它并转到“工具”>“获取工具和功能…”，以找到并安装“Visual Studio Tools for Unity”插件。

Visual Studio for Mac

Unity编辑器安装程序包括安装Visual Studio for Mac的选项。这是设置Visual Studio for Mac进行Unity调试的建议方法。

如果您的计算机上已经安装了Visual Studio for Mac，请打开它并转到“Visual Studio”>“扩展”>“从文件安装…”，以找到并安装“Visual Studio Tools for Unity”插件。

JetBrains Rider

您可以使用 JetBrains Rider 的默认安装版对 Windows 或 Mac 上的 Unity 代码进行调试。请访问JetBrains 网站安装它。

在 Unity 中指定外部脚本编辑器

安装代码编辑器后，打开 Unity，转到 首选项 > 外部工具，并将 外部脚本编辑器 设置为您使用的代码编辑器。

断点

断点允许您指定代码中希望暂停执行的位置。在您的外部代码编辑器中，您可以在希望调试器停下的代码行上设置断点。在代码编辑器位于断点时，您可以逐步查看变量的内容。

如果您已经将代码编辑器连接到 Unity 编辑器（请参阅将代码编辑器连接到 Unity 编辑器），则 Unity 编辑器将变为不响应状态，直到您在代码编辑器中选择继续选项或停止调试模式。

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

在 Unity 编辑器中调试

在 Unity 编辑器处于播放模式时，您可以调试运行在 Unity 编辑器中的 C# 代码。

要在编辑器中调试，您需要将编辑器的代码优化模式设置为 调试模式，然后您可以连接具有调试功能的代码编辑器。

要更改代码优化模式，请选择 Unity 编辑器状态栏 右下角的 调试按钮。

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

• 调试模式，您可以使用它来连接外部调试软件，但在编辑器中以播放模式运行项目时，会给 C# 性能带来较慢的表现。
• 发布模式，在编辑器中以播放模式运行项目时，会给 C# 性能带来更快的运行，但无法连接任何外部调试器。

当您单击状态栏上的调试按钮时，将弹出一个包含切换模式按钮的小窗口。窗口还会显示有关当前模式的信息，并描述在切换模式时会发生什么。

要更改 Unity 编辑器启动时的模式，请转到 编辑（macOS：Unity）> 首选参数 > 常规 > 启动时代码优化。

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

• ManagedDebugger
• Compilation.CompilationPipeline-codeOptimization
• Compilation.CodeOptimization.

您还可以重写编辑器启动时的模式，或禁用调试器监听套接字。为此，请在启动编辑器时使用以下命令行参数：

• -releaseCodeOptimization。以 发布 代码优化模式启动编辑器。
• -debugCodeOptimization。以 调试 代码优化模式启动编辑器。
• -disableManagedDebugger。以禁用调试器监听套接字的方式启动编辑器。

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

将您的代码编辑器连接到Unity编辑器的方法取决于您使用哪种代码编辑器，通常与您的代码编辑器常规调试过程中的不同选项。某些代码编辑器允许您选择要调试的Unity实例。有关您代码编辑器的具体说明，请参阅代码编辑器外部文档。有关如何在Visual Studio中实现此操作的说明，请参阅将Visual Studio连接到Unity编辑器。

当您已将代码编辑器连接到Unity编辑器并准备好开始调试时，请返回Unity编辑器并进入播放模式。

在Unity播放器中进行调试

编译Unity播放器以便进行调试

1. 转到文件 > 构建设置。
2. 在构建播放器之前启用开发构建开发构建包含调试符号并启用分析器。 更多信息
   参见 术语表和脚本调试选项。您还可以启用等待托管调试器选项以使播放器在执行任何脚本代码之前等待调试器连接。
3. 选择构建并运行。

将代码编辑器连接到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，转到调试 > 连接Unity调试器并选择要调试的Unity编辑器实例。

在以下示例图像中，有一个实例在编辑器中运行Unity，还有一个实例作为Android播放器运行。

使用Visual Studio调试Android和iOS设备

Android

要调试在Android设备上运行的Unity播放器，请使用USB或TCP连接到设备。例如，在Visual Studio中连接到Android设备，请选择调试 > 连接Unity调试器选项。将显示运行播放器实例的设备列表。

在这个示例中，Android设备通过USB和同一网络上运行的Unity编辑器和Visual Studio的工作站连接到Wi-Fi。

ChromeOS上的Android

Unity无法自动发现ChromeOS设备。要建立连接，请通过Android调试桥（adb）连接到设备。有关如何使用adbAndroid调试桥（ADB）。您可以使用ADB在构建后手动部署Android包（APK）。 更多信息
在术语表中查看的详细信息，请参阅Android Studio用户指南。

iOS

要调试在iOS设备上运行的Unity Player，请使用TCP连接到该设备。例如，要在Mac上的Visual Studio中连接到iOS设备，请选择调试 > 附加Unity调试器。将显示运行Player实例的设备列表。

请确保设备只有一个活动网络接口（建议使用Wi-Fi，关闭移动数据），且在IDE和设备之间没有防火墙阻止TCP端口（上图中为端口56000）。

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

调试器故障排除

大多数调试问题发生在代码编辑器无法找到Unity编辑器或Unity Player时。这意味着Unity编辑器或Player不能正确地附加调试器。因为调试器使用TCP连接到编辑器或Player，所以连接问题通常由网络引起。以下是一些您可以采取的基本连接故障排除步骤。

确保您已将调试器附加到正确的Unity实例

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

验证到Unity实例的网络连接

代码编辑器使用与Unity 性能分析器一个窗口，帮助您优化游戏。它可以显示在游戏的不同区域花费的时间。例如，它可以报告渲染、动画或在您的游戏逻辑中花费的时间百分比。 更多信息
在术语表中查看相同的机制来定位要调试的Unity实例。如果代码编辑器无法找到您预期的Unity实例，请尝试将该Unity性能分析器附加到该实例。如果Unity性能分析器也无法找到Unity实例，则您的代码编辑器或Unity实例运行的计算机上可能存在防火墙。如果设置了防火墙，请参阅检查防火墙设置。

确保设备只有一个活动网络接口

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

您可以通过查找Player日志由独立玩家创建的.log文件，其中包含记录事件，例如脚本执行时间、编译器版本和AssetImport时间。日志文件有助于诊断问题。 更多信息
在术语表中查看来确定Unity Player告诉IDE使用的IP地址。查找日志中的类似部分

多播"[IP] 10.0.1.152 [端口] 55000 [标志] 3 [指南] 2575380029 [编辑器ID] 4264788666 [版本] 1048832 [ID] iPhonePlayer(Example-iPhone):56000 [调试] 1 [包名] iPhonePlayer"到[225.0.0.222:54997]...

此信息表示 IDE 将尝试使用 IP 地址 10.0.1.152 和端口号 56000 连接到设备。这个 IP 地址和端口号必须可以从运行 IDE 的计算机访问。

检查防火墙设置

Unity 实例通过 TCP 连接与代码编辑器通信。在大多数 Unity 平台上，这个 TCP 连接发生在任意选择的端口上。通常，您无需知道这个端口，因为代码编辑器应该可以自动检测到。如果不起作用，请使用网络分析工具确定可能被阻止的端口号，这些端口号可能是运行代码编辑器的机器，或者是运行 Unity 实例的机器或设备上的。当你找到端口号时，请确保您的防火墙允许访问运行代码编辑器的机器和运行 Unity 实例的机器上的端口号。

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

如果调试器已连接到 Unity 实例但断点没有加载，则调试器可能无法找到代码的托管调试信息。托管代码调试信息存储在名为 .pdb 的文件中，位于磁盘上的托管程序集 (.dll 文件) 旁边。

当您启用正确的首选项和构建选项（请参阅 配置代码编辑器）时，Unity 会自动生成此调试信息。但是，Unity 无法为项目中托管插件生成调试信息。只有在相关的 .pdb 文件位于磁盘上 Unity 项目的托管插件旁边时，您才能从托管插件中调试代码。

防止设备锁屏

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

由于调试器引发的内存和线程泄漏

托管调试器的实现将泄漏一些 OS 级线程句柄和一些与线程相关的内存，以处理线程启动和关闭相关的某些竞争条件。实际上，这些泄漏很小，应该不会影响应用程序的资源使用。然而，当创建和销毁许多线程时，泄漏可能很明显。这种行为也可能使跟踪实际的内存泄漏变得困难，因此我们建议在调试内存泄漏时禁用脚本调试。

代码编辑器外部文档

• Visual Studio - 使用 Visual Studio Tools for Unity（Windows）
• Visual Studio for Mac - 使用 Visual Studio Tools for Unity（macOS）
• JetBrains Rider - 调试 Unity 应用程序