除錯工具總覽

本指南將介紹引擎中可用的除錯工具概覽。

Godot 內建強大的除錯器與效能分析工具，能協助你追蹤錯誤、在執行時檢查遊戲、監控重要指標，以及測量效能。還能在遊戲運作時視覺化碰撞方塊與導航多邊形。

你也可以選擇遠端除錯執行於其他裝置上的遊戲，並在遊戲執行時即時重新載入場景或程式碼的變更。

輸出面板

輸出面板可讓你查看專案或編輯器輸出的文字（例如由 @tool 腳本輸出的內容）。更多資訊請參閱 輸出面板。

除錯器面板

Godot 的許多除錯工具都屬於「除錯器」面板。你可以在 除錯器面板 取得更多相關資訊。

除錯選單選項

在編輯器內執行遊戲時，你可以開啟或關閉一些常用的除錯選項，這些選項有助於你除錯遊戲。

你可以在編輯器的 除錯 選單中找到這些選項。

以下是這些選項的說明：

使用遠端除錯部署

啟用此選項後，使用一鍵部署時，產生的可執行檔會嘗試連線到本機 IP，以便進行遠端除錯。此功能主要用於遠端（例如行動裝置）除錯。若只需在本機使用 GDScript 除錯器，則無需啟用。

使用網路檔案系統進行精簡部署

此選項可加快大容量遊戲於遠端裝置上的測試速度。

啟用 使用網路檔案系統進行精簡部署 後，部署遊戲時不會匯出完整遊戲，而是建立一個最小的可執行檔，編輯器會透過網路提供專案檔案。

此外，在 Android 裝置上，專案會透過 USB 線進行部署，以加快速度。

顯示碰撞形狀

啟用此選項後，碰撞形狀與 RayCast 節點（2D 與 3D）會在運作中的專案裡以可視方式顯示。

顯示路徑

啟用後，路徑節點所使用的曲線資源會在遊戲運作時顯示出來。

顯示導航

啟用後，導航網格和多邊形會在執行中的專案中顯示。

顯示迴避物件

啟用此選項後，避障物件的形狀、半徑與速度都會在運作中的專案中顯示。

偵錯 CanvasItem 重繪

啟用此選項後，2D 物件的重繪請求會在執行中的專案中以閃爍效果顯示，有助於偵測低效能模式下的問題。

同步場景變更

啟用此選項後，無論在本機或遠端裝置，只要你在編輯器更改場景，運作中的專案都會即時同步。若搭配網路檔案系統使用，遠端同步效率會更高。

同步腳本變更

啟用後，於編輯器修改腳本時，運作中的專案會即時重新載入變更。搭配網路檔案系統於遠端裝置使用時，效率更佳。

保持除錯伺服器開啟

啟用後，編輯器的除錯伺服器將保持開啟，並可監聽從編輯器外部啟動的新除錯連線。

自訂執行實例...

這會開啟一個對話視窗，讓你指定要同時執行多少個遊戲實例，並可為每個實例設定命令列參數。此功能特別適合開發與除錯多人遊戲時使用。

啟用多重實例

啟用此選項後，當你執行專案時，編輯器會同時啟動多個專案實例。

下方可選擇要同時執行的實例數量。

如果啟用但只設為 1，效果與未啟用此功能相同。

主要執行參數

這些參數會傳遞給每個執行的專案實例，除非為某個特定實例啟用「覆寫主要執行參數」。

請注意，這些參數需以空白分隔。

小訣竅

你可以在腳本中透過 get_cmdline_args 取得這些參數。

警告

即使未勾選「啟用多重實例」，執行專案時仍會傳遞這些參數。

主要功能標籤

這些功能標籤會傳遞給每個實例，除非在特定實例啟用「覆寫主要標籤」。

覆寫主要執行參數

啟用此選項後，執行專案時，「主要執行參數」中的參數將不會傳遞給此特定實例。

啟動參數

這些是只會傳遞給此特定執行實例的參數，除非啟用「覆寫主要執行參數」，否則會與「主要執行參數」合併。

覆寫主要標籤

啟用此選項後，「主要功能標籤」中的標籤將不會傳遞給此特定實例。

功能標籤

這些標籤會傳遞給此特定實例，除非啟用「覆寫主要標籤」，否則會與「主要功能標籤」合併。

警告

若需傳遞「User」參數，並在腳本中用 get_cmdline_user_args 取得，需在參數前加上兩個減號及一個空白，例如 -- one two three。

請注意，這些減號會套用到每個實例的「啟動參數」，當主參數與啟動參數同時存在時，可能會造成混淆。

例如，若你在「主要執行參數」填入 -- one two three，而「啟動參數」又填入 -- four five six，最終命令列會變成 one two three -- four five six，這是因為「啟動參數」中的 -- 也會被加上。

腳本編輯器除錯工具與選項

腳本編輯器有專屬的除錯工具，可搭配中斷點使用，還有兩個選項。這些中斷點工具也可於除錯器的 Debugger 分頁中找到。

小訣竅

您可以透過點選腳本編輯器左側的裝訂線（行號左側）來建立斷點。將滑鼠懸停在該排水溝上時，您會看到出現一個透明的紅點，點擊放置斷點後，該紅點會變成不透明的紅點。再次點選紅點即可刪除斷點。以這種方式建立的斷點在編輯器重新啟動後仍然存在，即使退出編輯器時未儲存腳本也是如此。

你也可以在 GDScript 腳本中使用 breakpoint 關鍵字，於原始碼內建立中斷點。與用滑鼠點擊行號邊緣建立的中斷點不同，這種做法可讓中斷點隨版本控制同步到不同機器。

中斷點 按鈕會像中斷點一樣導致腳本的中斷. 繼續 使遊戲在中斷點處暫停後繼續. Step Over 進入下一行程式碼, 如果可能的話, Step Into 進入一個函式. 否則, 它與 Step Over 做同樣的事情.

使用外部編輯器除錯 選項可讓你用外部編輯器除錯遊戲。你可在 編輯器設定 > 快捷鍵 > 除錯器 設定此功能的快捷鍵。

當偵錯器在斷點處中斷時，腳本編輯器的裝訂線中會顯示綠色三角形箭頭。此箭頭指示偵錯器中斷的程式碼行。

除錯專案設定

專案設定中有 Debug 分類，下有多個子分類可設定各種除錯相關選項。如需調整這些設定，請先啟用 進階設定。

設定

這些都是一些常規的設定，比如將目前的 FPS 列印到**輸出**面板，剖析時的最大函式量等。

檔案日誌

你可以於此設定將主控台輸出與錯誤訊息記錄到檔案。

GDScript

這些設定可讓你啟用或停用特定的 GDScript 警告（如未使用變數警告），也能完全關閉警告。詳細請見 GDScript 警告系統。

著色器語言

這些設定能讓你切換特定著色器警告（例如未使用變數），或關閉所有警告。

Canvas 項目

這些設定用於偵錯 Canvas 項目的重繪行為。

形狀

Shapes中你可以調整形狀的顏色, 這些形狀只出現在除錯的目的, 如碰撞和導覽形狀.

場景面板遠端檢視

在編輯器中執行遊戲時，場景 面板上方會出現 遠端 與 本機 兩個選項。選用 遠端 時，你可以檢查並修改運作中專案裡的節點參數。

備註

編輯器中也有部分與除錯相關的設定，可在 編輯器設定 的 Network > Debug 和 Debugger 區段找到。