Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

调试工具概述

本指南将概述引擎中可用的调试工具.

Godot自带强大的调试器和剖析器, 可以追踪bug, 在运行时检查你的游戏, 监控重要指标, 并测量性能. 它还提供了在运行游戏中可视化碰撞框和导航多边形的选项.

最后, 你可以选择调试在远程设备上运行的游戏, 并在游戏运行时重新加载对你的场景或代码的修改.

Output Panel

The output panel allows you to see text printed by the project, but also by the editor (e.g. from @tool scripts). You can find information about in Output panel.

调试器面板

Godot 的许多调试工具都是“调试器”面板的一部分，你可以在 调试器面板 中找到相关信息。

调试菜单选项

在编辑器中运行游戏时, 有几个常见的调试选项可以切换为开或关, 以帮助你调试游戏.

你可以在编辑器菜单调试中找到这些选项。

下面是这些选项的说明：

使用远程调试部署

启用此选项后，使用一键部署时，可执行文件将尝试连接到此计算机的 IP，以便调试正在运行的项目。此选项旨在用于远程调试（通常用于移动设备）。如果在本地使用 GDScript 调试器，则不需要启用此选项。

使用网络文件系统进行小型部署

这个选项加快了在远程设备上进行大足迹游戏的测试.

When Small Deploy with Network Filesystem is on, instead of exporting the full game, deploying the game builds a minimal executable. The editor then provides files from the project over the network.

另外，在 Android 系统上，游戏采用 USB 线部署，加快部署速度。

显示碰撞区域

When this option is enabled, collision shapes and raycast nodes (for 2D and 3D) will be visible in the running project.

显示路径

启用该选项时，路径节点的曲线资源将在项目运行时可见。

显示导航

启用该选项时，导航网格和多边形将在项目运行时可见。

显示避障

启用该选项时，避障对象的形状、半径、速度都将在项目运行时可见。

调试 CanvasItem 重绘

启用该选项时，2D 对象的重绘请求将在项目运行时可见（短暂的闪光）。可用于低处理器模式下的故障排除。

同步场景修改

启用该选项时，在编辑器中对场景的任何修改都会被应用于正在运行的项目中。当使用于远程设备时，启用网络文件系统能提高编辑效率。

同步脚本修改

启用该选项时，任何保存的脚本都会被正在运行的项目重新加载。当使用于远程设备时，启用网络文件系统能提高编辑效率。

调试服务器保持开放

启用该选项时，编辑器的调试服务器将保持开放，监听在编辑器本身之外开始的新会话。

自定义运行实例...

这会打开一个窗口，允许你指定 Godot 同时运行游戏的多个实例，并指定每个实例的命令行参数。这在构建和调试多人游戏时尤其有用。

启用多实例

该选项启用后，运行项目时会同时运行多个实例。

该勾选框下有选择器，用于指定同时运行实例的数量。

勾选后将该数值设定为 1 等价于不勾选。

主要运行参数

这些参数将在你运行项目时传递给**每一个**项目实例，除非你为特定实例选择了“Override Main Run Args”下的“Enabled”选项。

请注意，这些参数是以空格分隔的。

小技巧

你可以通过使用 get_cmdline_args 在脚本中访问这些参数。

警告

即使你取消勾选“Enable Multiple Instances”，在运行项目时，这些参数仍然会被传递。

主要特性标签

这些是当你运行项目时会传递给**每一个**项目实例的特性标签，除非你为特定实例选择了“Override Main Tags”下的“Enabled”选项。

覆盖主要运行参数

启用此选项后，在运行项目时，“Main Run Args” 字段中的参数**不会传递**给该特定实例。

Launch Arguments

These are the arguments that will be passed to this specific instance of the project when you Run Project. They will be combined with the "Main Run Args" unless you select "Enabled" under "Override Main Run Args".

Override Main Tags

When this is enabled, the tags in the "Main Feature Tags" field will not be passed to this specific instance of the project when you Run Project.

Feature Tags

These are the feature tags that will be passed to this specific instance of the project when you Run Project. They will be combined with the "Main Feature Tags" unless you select "Enabled" under "Override Main Tags".

警告

If you want to pass "User" arguments, that can be accessed with get_cmdline_user_args then you must prefix them with two dashes and a space like -- one two three.

Be aware that these dashes will apply to arguments added later in the "Launch Arguments" on a per instance basis, which can cause some confusion when combining the Main Run Args and Launch Arguments.

If you place -- one two three in the "Main Run Args" and -- four five six in the "Launch Arguments" then the final command line arguments will be one two three -- four five six. This is because the -- is repeated in the "Launch Arguments".

脚本编辑器调试工具和选项

脚本编辑器有自己的一套调试工具，用于断点和两个选项。断点工具也可以在调试器的调试器选项卡中找到。

小技巧

You can create a breakpoint by clicking the gutter in the left of the script editor (on the left of the line numbers). When hovering this gutter, you will see a transparent red dot appearing, which turns into an opaque red dot after the breakpoint is placed by clicking. Click the red dot again to remove the breakpoint. Breakpoints created this way persist across editor restarts, even if the script wasn't saved when exiting the editor.

You can also use the breakpoint keyword in GDScript to create a breakpoint that is stored in the script itself. Unlike breakpoints created by clicking in the gutter, this keyword-based breakpoint is persistent across different machines when using version control.

断点 按钮会像断点一样导致脚本的中断. 继续 使游戏在断点处暂停后继续. Step Over 进入下一行代码, 如果可能的话, Step Into 进入一个函数. 否则, 它与 Step Over 做同样的事情.

The Debug with External Editor option lets you debug your game with an external editor. You can set a shortcut for it in Editor Settings > Shortcuts > Debugger.

当调试器在断点处中断时，脚本编辑器的排水沟中会显示一个绿色的三角箭头。此箭头表示调试器中断的代码行。

调试项目设置

In the project settings, there is a Debug category with subcategories which control different things. Enable Advanced Settings to change these settings.

Settings（设置）

这些都是一些常规的设置，比如将当前的 FPS 打印到输出面板，剖析时的最大函数量等。

File Logging

These settings allow you to log console output and error messages to files.

GDScript

These settings allow you to toggle specific GDScript warnings, such as for unused variables. You can also turn off warnings completely. See GDScript 警告系统 for more information.

Shader Language

These settings allow you to toggle specific shader warnings, such as for unused variables. You can also turn off warnings completely.

Canvas Items

These settings are for canvas item redraw debugging.

Shapes（形状）

Shapes中你可以调整形状的颜色, 这些形状只出现在调试的目的, 如碰撞和导航形状.

遥控场景面板

当在编辑器中运行游戏时，场景面板顶部会出现两个选项，即远程和本地。当使用远程时，你可以检查或改变运行项目中的节点参数。

备注

一些与调试有关的编辑器设置可以在 Editor Settings 内找到, 在 Network > Debug and Debugger 部分.