故障排除

这个页面列出了使用 Godot 时的常见问题以及可能的解决办法。

参见

关于 Godot 编辑器 Web 版本特定的注意事项，请参阅 使用 Web 编辑器 。

编辑器运行缓慢，占用了我所有的 CPU 和 GPU 资源，使我的电脑变得嘈杂

这是一个已知问题，尤其是在 macOS 上，因为大多数 Mac 都有 Retina 显示屏。由于 Retina 显示器的像素密度更高，因此所有内容都必须以更高的分辨率渲染。这会增加 GPU 上的负载并降低感知性能。

有几种衡量性能和电池续航的方法，包括：

  • 在 3D 模式下，单击左上角的透视按钮并启用半分辨率。现在 3D 视口就会以半分辨率渲染，速度最多可以提高到原来的 4 倍。

  • Open the Editor Settings and increase the value of Low Processor Mode Sleep (µsec) to 33000 (30 FPS). This value determines the amount of microseconds between frames to render. Higher values will make the editor feel less reactive, but will help decrease CPU and GPU usage significantly.

  • If you have a node that causes the editor to redraw continuously (such as particles), hide it and show it using a script in the _ready() method. This way, it will be hidden in the editor, but will still be visible in the running project.

编辑器在我的可变刷新率显示器（G-Sync/FreeSync）上出现卡顿和闪烁的情况

这是一个已知问题。 可变刷新率显示器需要不断调整其伽玛曲线，以便随着时间的推移发出一致的光量。当刷新率变化很大时，这可能会导致图像的黑暗区域出现闪烁，这是因为 Godot 编辑器仅在必要时重绘。

这有几种解决办法：

  • Enable Interface > Editor > Update Continuously in the Editor Settings. Keep in mind this will increase power usage and heat/noise emissions since the editor will now be rendering constantly, even if nothing has changed on screen. To alleviate this, you can increase Low Processor Mode Sleep (µsec) to 33000 (30 FPS) in the Editor Settings. This value determines the amount of microseconds between frames to render. Higher values will make the editor feel less reactive, but will help decrease CPU and GPU usage significantly.

  • 或者，在显示器或图形驱动程序中禁用可变刷新率。

  • VRR 闪烁这个问题在某些显示器上，可以通过你的显示器的 OSD 中的 VRR 控制或微调暗区选项来减少。这些选项可能会增加输入延迟或导致黑色失真。

  • 如果在使用 OLED 显示器，可以在编辑器设置中使用 Black (OLED) 编辑器主题预设。因为 OLED 显示器的出色的黑阶表现，这可以隐藏 VRR 闪烁。

编辑器或项目花了很长时间才启动

When using one of the Vulkan-based renderers (Forward+ or Mobile), the first startup is expected to be relatively long. This is because shaders need to be compiled before they can be cached. Shaders also need to be cached again after updating Godot, after updating graphics drivers or after switching graphics cards.

如果这个问题在首次启动后依然存在，那么这是 Windows 上的一个已知错误，当你连接了特定的 USB 外设时就会出现 。特别是，海盗船的 iCUE 软件似乎引起了该错误。尝试将 USB 外设的驱动程序更新为最新版本。如果错误仍然存在，则需要在打开编辑器之前断开故障外围设备的连接。然后，你可以再次连接外围设备。

Portmaster 等防火墙软件可能会屏蔽调试端口，导致项目启动时间变长，并且无法在编辑器中使用调试功能（例如查看 print() 的输出）。变通方法是在“编辑器设置”中修改项目所使用的调试端口（网络 > 调试 > 远程端口）。默认值是 6007；可以尝试设成大于 1024 的值，比如 7007。

On Windows, when loading the project for the first time after the PC is turned on, Windows Defender will cause the filesystem cache validation on project startup to take significantly longer. This is especially noticeable in projects with a large number of files. Consinder adding the project folder to the list of exclusions by going to Virus & threat protection > Virus & threat protection settings > Add or remove exclusions.

点击系统控制台后，Godot 编辑器没有响应

在启用了系统控制台的 Windows 上运行 Godot 时，你可以通过在命令窗口中单击来意外启用选择模式。Windows 的这种特定行为会暂停应用程序，以便你在系统控制台内选择文本。Godot 无法覆盖此系统特定的行为。

要解决此问题，请选择系统控制台窗口，然后按 Enter 退出选择模式。

手动移动Godot编辑器的macOS dock 图标之后，会出现多余的编辑器图标

如果你打开 Godot 编辑器并手动改变 dock 图标的位置，然后重启编辑器，你会在 dock 的最右边看到一个重复的 dock 图标。

这是由于 macOS dock 的设计限制造成的。解决这个问题的唯一已知方法是将项目管理器和编辑器合并为一个进程，这意味着项目管理器在启动编辑器时不再产生一个单独的进程。虽然使用单一进程实例会带来一些好处，但由于任务的复杂性，完成这个功能没有列入我们近期的工作计划。

为了避免这个问题，保持 Godot 编辑器的 dock 图标在 macOS 创建的默认位置。

在项目管理器和编辑器窗口的左上角出现“NO DC”之类的文本

这是由于 NVIDIA 显卡驱动程序注入了覆盖显示信息造成的。

要在 Windows 上禁用此覆盖，请在 NVIDIA 控制面板中将图形驱动程序设置恢复为默认值。

要在 Linux 上禁用此覆盖，请打开 nvidia-settings，转到 X Screen 0 > OpenGL Settings，然后取消选中 Enable Graphics API Visual Indicator。

在项目管理器和编辑器窗口右下角出现一个麦克风或刷新的图标

这是由于 NVIDIA 图形驱动程序注入覆盖以显示 ShadowPlay 录制的即时重播信息造成的。此覆盖只能在 Windows 上看到，因为 Linux 不支持 ShadowPlay。

要禁用此覆盖，请按 Alt + Z（NVIDIA 覆盖的默认快捷方式）并在 NVIDIA 覆盖中禁用设置 > HUD 布局 > 状态指示器。

你也可以选择安装取代 GeForce Experience 的新的 NVIDIA 程序 <https://www.nvidia.com/en-us/software/nvidia-app/>，这样就不会遇到这个问题。与 GeForce Experience 不同的是，NVIDIA 程序会在屏幕的角落而不是每个窗口的角落绘制回放指示器。

编辑器或项目显示得过于锐利或模糊

正确的外观（左），由于显卡驱动的锐化而导致的过度锐化的外观（右）

正确的外观（左），由于显卡驱动的锐化而导致的过度锐化的外观（右）

如果编辑器或项目看起来过于锐利，这可能是由于你的图形驱动程序强制对所有 Vulkan 或 OpenGL 应用程序进行图像锐化。你可以在图形驱动程序的控制面板中禁用此行为：

  • NVIDIA（Windows）：打开开始菜单，选择 NVIDIA 控制面板。打开左侧的管理 3D 设置选项卡。在中间的列表中，滚动到图像锐化，并将其设置为关闭锐化。

  • AMD（Windows）：打开开始菜单，选择 AMD 软件。点击右上角的设置 "齿轮 "图标。转到图形选项卡，然后禁用 Radeon 图像锐化。

如果编辑器或者项目看起来过于模糊，这可能是由于 FXAA 被你的显卡驱动强制应用到所有的 Vulkan 或者 OpenGL 应用程序上。

  • NVIDIA（Windows）：打开开始菜单并选择 NVIDIA 控制面板。打开左侧的管理 3D 设置选项卡。在中间的列表中， 滚动到平滑设置 - FXAA 并将其设置为应用程序控制的。

  • NVIDIA（Linux）：打开应用程序菜单，选择 NVIDIA X 服务器设置。在左侧选择 Antialiasing Settings，取消对 Enable FXAA 的勾选。

  • AMD (Windows): Open the start menu and choose AMD Software. Click the settings "cog" icon in the top-right corner. Go to the Graphics tab, scroll to the bottom and click Advanced to unfold its settings. Disable Morphological Antialiasing.

像是 vkBasalt 这种第三方开发的供应的工具可能会强迫所有的 Vulkan 应用程序开启锐化或者 FXAA。你可能也需要检查他们的设置。

当你变更过了显卡驱动和第三方工具中的设置后，重启 Godot 去应用这些设置。

如果你仍然希望在其他应用程序上强制锐化或 FXAA，建议你使用显卡驱动控制面板提供的应用程序配置系统，针对每个应用程序的进行设置。

此编辑器或项目看起来颜色很淡

在 Windows 上，这通常是由不正确的操作系统或显示器设置引起的，因为 Godot 目前不支持 HDR 输出（即使它可能在内部以 HDR 渲染）。

由于`大多数显示器并非被设计为在 HDR 模式下显示 SDR 内容 <https://tftcentral.co.uk/articles/heres-why-you-should-only-enable-hdr-mode-on-your-pc-when-you-are-viewing-hdr-content>`__，建议在未运行使用 HDR 输出的应用程序时在 Windows 设置中禁用 HDR。在 Windows 11 上，可以通过按 Windows + Alt + B 来完成该操作（该快捷方式是 Xbox Game Bar 应用程序的一部分）。要根据当前正在运行的应用程序自动切换 HDR，你可以使用 AutoActions。

如果你坚持启用 HDR，可以通过确保显示器配置为使用 HGIG 色调映射（而不是 DTM），然后`使用 Windows HDR 校准应用程序 <https://support.microsoft.com/en-us/windows/calibrate-your-hdr-display-using-the-windows-hdr-calibration-app-f30f4809-3369-43e4-9b02-9eabebd23f19>`__ 来稍微改善结果。强烈建议在使用 HDR 时使用 Windows 11 而不是 Windows 10。不过，最终结果可能仍不如在显示器上禁用 HDR。

计划在未来版本中支持 HDR 导出。

从挂起状态恢复 PC 后，编辑器/项目冻结或显示出现故障

This is a known issue on Linux with NVIDIA graphics when using the proprietary driver. There is no definitive fix yet, as suspend on Linux + NVIDIA is often buggy when OpenGL or Vulkan is involved. The Compatibility rendering method (which uses OpenGL) is generally less prone to suspend-related issues compared to the Forward+ and Mobile renderers (which use Vulkan).

NVIDIA驱动程序提供了一个实验性选项可在挂起后保护视频内存用以解决这个问题。据报道，该选项与较新的 NVIDIA 驱动程序版本配合使用效果更好。

为了避免丢失工作内容，请在使电脑进入睡眠状态之前将场景保存在编辑器中。

项目在编辑器中正常运行，但在导出后无法加载部分文件

这通常是由于忘记在导出对话框中指定非资源文件过滤器而导致的。默认情况下，Godot 只会将实际的资源包含到 PCK 文件中。一些常用的文件，例如 JSON 文件，不会被视为资源。例如，如果你在导出的项目中加载 test.json，则需要在非资源导出过滤器中指定 *.json。有关更多信息，请参阅 资源选项。

另外，请注意，导出的项目永远不会包含名字以点开头的文件和文件夹。这是为了防止将 .git 等版本控制文件夹包含在导出的 PCK 文件中。

在 Windows 上，也可能是大小写敏感性的问题。如果你在脚本里引用资源时所使用的大小写与文件系统中的不符，在导出项目后就会载入失败。这是因为虚拟 PCK 文件系统是大小写敏感的，而 Windows 的文件系统是大小写不敏感的。

The project crashes frequently or instantly after opening it from the project manager

This could be caused by a number of things such as an editor plugin, GDExtension addon, or something else. In this scenario it's recommended that you open the project in recovery mode, and attempt to find and fix whatever is causing the crashes. See the Project Manager page for more information.