故障排除

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

参见

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

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

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

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

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

  • 打开编辑器设置并将 低处理器模式睡眠（微秒） 的值增加到 33000 （30 FPS）。 该值确定要渲染的帧之间的 微秒 量。 较高的值将降低编辑器反应性，但可显著降低 CPU 和 GPU 使用率。

  • 如果有某个节点导致编辑器连续重新绘制（例如粒子），请将其隐藏并使用 _ready() 方法在脚本中显示它。这样，它将隐藏在编辑器中，但仍在正在运行的项目中可见。

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

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

这有几种解决办法：

  • 在编辑器设置中启用 界面 > 编辑器 > 持续更新。 现在即使屏幕没有变化，编辑器也将不断渲染，这会增加功耗、造成热量和噪音的更大排放。 为了缓解这种情况，你可以在编辑器设置中将 低处理器模式睡眠（微秒） 增加到 33000（30 FPS）。 该值确定要渲染的帧之间的 微秒 量。 较高的值将降低编辑器反应性，但可显著降低 CPU 和 GPU 使用率。

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

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

  • 如果在使用 OLED 显示器，可以在编辑器设置中使用 Black (OLED) 预设。因为 OLED 显示器的出色的黑阶表现，这个预设将会有助于减弱 VRR 闪烁。

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

当使用基于Vulkan的渲染器（Forward+ 或 Forward Mobile）时，第一次启动将会话费比较长的时间。这是因为着色器需要在缓存之前进行编译。更新Godot、更新显卡驱动或切换显卡后，着色器也需要重新缓存。

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

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

点击系统控制台后，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。

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

Alternatively, you can install the new NVIDIA app <https://www.nvidia.com/en-us/software/nvidia-app/&gt; which replaces GeForce Experience and does not suffer from this issue. Unlike GeForce Experience, the NVIDIA app draws the replay indicator in the corner of the screen as opposed to the corner of each window.

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

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

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

如果编辑器或项目看起来过于锐利，这可能是由于你的图形驱动程序强制对所有 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): 打开开始菜单并选择**AMD 软件**。单击 设置右上角的“齿轮”图标。转到**图形**选项卡， 滚动到底部并单击**高级**以展开其设置。禁用**形态抗锯齿**。

像是 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>`，建议在未运行应用程序时在Windows设置中禁用HDR 使用 HDR 输出。在 Windows11 上，可以通过按下 Windows + Alt + B （此快捷方式是 Xbox Game Bar 应用程序的一部分）。如果要自动开关HDR模式的话，你可以使用 AutoActions <https://github.com/Codectory/AutoActions&gt; 。

如果你坚持要启用 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&gt; 。在使用HDR时，强烈建议使用Windows 11而不是Windows 10。 不过，最终结果仍然可能不如在显示器上禁用HDR。

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

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

当在 Linux 上使用 NVIDIA 的专用图形驱动程序时便会出现这个已知的问题。目前还没有明确的解决方案，因为当涉及 OpenGL 或 Vulkan 时，Linux+NVIDIA 上的挂起通常会出现问题。与 Forward+ 和 ForwardMobile 渲染方法（使用 Vulkan ）相比，兼容性渲染方法（采用 OpenGL ）通常不太容易出现挂起相关问题。

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

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

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

这通常是在导出对话框中忘记筛选非资源文件所导致的。默认情况下，Godot只会将实际的资源包含在 PCK 文件中。一些常用的文件，例如 JSON 文件，不会被视为资源。例如，当你在导出的项目中加载 test.json 时，你需要在非资源导出过滤器中指定 *.json。详见：资源选项。

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

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