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 時會遇到的場景問題與可行的解決方案。

也參考

關於 Godot 編輯器 HTML5 版本的特定注意事項，請參考 執行編輯器。

編輯器運作緩慢，佔用了我所有的 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顯示器，可以在編輯器設定中使用**黑色（OLED）**預設。因為OLED顯示器的出色的黑階表現，這個預設將會有助於減弱VRR閃爍。

編輯器或專案花了很多時間才打開

When using one of the RenderingDevice-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 上的一個 已知 Bug ，會發生在有連接到特定 USB 週邊裝置時。特別是 Corsair 的 iCUE 軟體似乎會導致這個問題。請試著更新這些 USB 週邊裝置的驅動程式至最新版本。若仍然遇到此 Bug，則必須在開啟編輯器時先斷開有問題的週邊裝置。開啟後即可重新接上。

Portmaster等防火牆軟體可能會出現除錯端口，導致專案啟動時間變長，並且無法在編輯器中使用調試功能（例如查看``print()``的輸出）。變通方法是在「編輯器設定」中專案所使用的偵錯連接埠（網路 > 偵錯 > 遠端連接埠）。預設值為``6007``；可以嘗試設定成大於``1024``的值，例如``7007``。

在 Windows 系統中，電腦開機後第一次載入專案時，Windows Defender 會導致專案啟動時的檔案系統快取驗證時間明顯延長。這在擁有大量檔案的專案中尤為明顯。 您可以考慮將專案資料夾加入排除清單，方法是前往「病毒與威脅防護」>「病毒與威脅防護設定」>「新增或移除排除項目」。

點擊系統主控台後，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 版面配置 > 狀態指示器 」。

或者，您可以安裝 新 NVIDIA 應用程式 <https://www.nvidia.com/en-us/software/nvidia-app/> ，它取代了 GeForce Experience，並且沒有這個問題。與 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)： 開啟「開始」選單並選擇「AMD Software」。點擊右上角的設定「齒輪」圖示。前往「圖形」分頁，捲動至底部並點擊「進階」以展開其設定。停用「形態抗鋸齒」。

像是 vkBasalt 這種協力廠商開發的供應的工具可能會強迫所有的 Vulkan 應用程式開啟銳化或者 FXAA。你可能也需要檢查他們的設定。

當你變更過了顯卡驅動和協力廠商工具中的設定後，重啟 Godot 去應用這些設定。

如果您仍然希望在其他應用程式上強制銳化或 FXAA，建議你使用顯卡驅動控制台提供的應用程式配置系統，針對每個應用程式的進行設定。

從掛起狀態恢復 PC 後，編輯器/專案凍結或顯示出現故障

使用 NVIDIA 專有驅動程式時，在 Linux 系統上會出現這個已知問題。由於 Linux + NVIDIA 在涉及 OpenGL 或 Vulkan 時，暫停功能經常出現錯誤，因此目前沒有明確的解決方案。相較於 Forward+ 和 Mobile 算繪器（使用 Vulkan），相容性算繪方法（使用 OpenGL）通常比較不容易發生與暫停相關的問題。

NVIDIA驅動程式提供了一個 實驗性 選項可在掛起後保護影片記憶體 用以解決這個問題。據報導，此選項與較新的 NVIDIA 驅動程式版本配合使用效果更好。

為了避免丟失工作內容，請在使電腦進入睡眠狀態之前將場景保存在編輯器中。

專案可以從編輯器裡執行，但是從匯出的版本執行時無法載入某些檔案

這個問題通常時因為忘記在 [匯出] 對話框中為非資源檔案指定篩選器導致的。預設情況下，Godot 只會將真正的 資源 (Resource) 打包進 PCK 檔案內。有些常用的檔案，如 JSON 檔，並不屬於資源。舉例來說，若在匯出的專案中載入 test.json ，則需要在非資源匯出篩選器內指定 *.json 。更多資訊請參考 資源路徑 。

另外，請注意，匯出的專案永遠不會包含名字以點開頭的檔和資料夾。這是為了防止將 .git 等版本控制資料夾包含在匯出的 PCK 檔中。

而在 Windows 上，這個問題還可能是因為 大小寫區分 問題導致的。若在腳本中以與檔案系統不同的大小寫來參照資源，則匯出專案之後就會載入失敗。這是因為虛擬 PCK 檔案系統是有區分大小寫的，而 Windows 的檔案系統則預設不區分大小寫。

專案從專案管理員開啟後，頻繁或立即發生程式崩潰

這可能是由許多因素引起的，例如編輯器外掛、GDExtension 擴充套件或其他問題。在這種情況下，建議您以復原模式開啟專案，並嘗試找出並修復導致崩潰的原因。有關更多資訊，請參閱 專案管理員頁面。