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 主要是以 C++ 開發的專案，並 採用 SCons 作為建置系統。我們喜歡 SCons，因為它讓建置系統易於維護且設定簡單，因此從原始碼編譯 Godot 只需執行以下指令：

scons

這會為你目前的平台、作業系統與架構產生一個編輯器版本。你可以透過指定目標、平台，和/或處理器架構來改變建置內容。舉例來說，若要建置用於執行匯出遊戲的匯出樣板，可以執行：

scons target=template_release

如果你打算除錯或開發引擎本身，建議啟用 dev_build 選項，以啟用僅供開發階段使用的除錯程式碼：

scons dev_build=yes

下方各節將進一步說明這些及其他通用選項。但在編譯 Godot 前，你需要先安裝一些必要套件。請參考各平台的相關文件：

這些文章將詳細說明如何在各平台設定環境並進行編譯。你可以隨時搭配本篇內容與平台專屬文件，查閱平台專屬與通用的建置設定選項。

使用多執行緒

建置過程所需時間會依你的電腦效能而異。預設情況下，Godot 的 SCons 設定會使用除了 1 條之外的所有 CPU 執行緒（以在編譯期間保持系統回應）。若系統僅有 4 條或更少的執行緒，則預設會使用全部執行緒。

若要調整 SCons 使用的 CPU 執行緒數量，請使用 -j<threads> 參數來指定建置時要使用的執行緒數。

使用 12 條執行緒的範例：

scons -j12

平台選擇

Godot 的建置系統會先偵測可支援建置的平台。若某平台未被偵測到，則不會出現在可用平台列表中。各平台的建置需求會在本教學後續章節中說明。

只需執行 scons 即可啟動 SCons。若未指定平台，SCons 會依據主機平台自動偵測目標平台，並直接為該目標平台開始建置。

若要列出所有可用的目標平台，請執行 scons platform=list：

scons platform=list
scons: Reading SConscript files ...
The following platforms are available:

    android
    ios
    linuxbsd
    macos
    web
    windows

Please run SCons again and select a valid platform: platform=<string>

若要為特定平台（例如 linuxbsd）進行建置，請加上 platform=``（或簡寫 ``p=）參數執行：

scons platform=linuxbsd

產生的執行檔

產生的執行檔會放在 bin/ 子資料夾中，命名慣例如下：

godot.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]

依照上述建置範例，產生的檔案名稱會如下：

ls bin
bin/godot.linuxbsd.editor.x86_64

這表示這個執行檔是專為 Linux 或 *BSD （ 非 同時支援兩者）所建，未經最佳化，包含完整的編輯器，且為 64 位元版本。

相同設定下的 Windows 執行檔則會長這樣：

C:\godot> dir bin/
godot.windows.editor.64.exe

由於該執行檔包含了專案管理員、編輯器及所有執行遊戲所需功能，你可以將它複製到任何位置。但這個執行檔缺少匯出到其他平台所需的資料。要匯出到不同平台，需安裝匯出樣板（可從 godotengine.org 下載，或自行建置）。

此外，還有一些可用於所有建置目標的標準選項，詳見以下說明。

建置目標

target 選項用來控制是否建置編輯器以及是否啟用除錯旗標。最佳化等級（optimize）與是否包含除錯符號（debug_symbols）則與 target 分開設定。各模式代表：

  • target=editor：建置編輯器執行檔（定義：TOOLS_ENABLED 與 DEBUG_ENABLED）

  • target=template_debug：建置除錯版匯出樣板（定義：DEBUG_ENABLED）

  • target=template_release：建置發行版匯出樣板

在所有 PC 平台（Linux、Windows、macOS）上，預設會啟用編輯器；其他平台則預設關閉。若未啟用編輯器，則產生的執行檔僅能執行專案，無法使用編輯器與專案管理員。

可用的 命令列參數 會依建置類型而有所不同。

scons platform=<platform> target=editor|template_debug|template_release

開發與發行別名

當進行開發用途建置（用於偵錯或 效能分析 工具）時，與發行（正式版）建置的目標不同，通常會偏重偵錯功能或簡化設定，而發行建置則以產生更快更小的執行檔為主。

Godot 提供兩個常用別名以因應這些需求：

  • dev_mode=yes 是 verbose=yes warnings=extra werror=yes tests=yes 的別名。啟用此模式會將警告當作錯誤處理（類似 Godot 的 CI 設定），並建置 單元測試，方便你在本機執行測試。

  • production=yes 是 use_static_cpp=yes debug_symbols=no lto=auto 的別名。靜態連結 libstdc++ 能提升 Linux 二進位的可攜性。此別名會在編譯 Linux、Web 與使用 MinGW 的 Windows 時啟用連結時最佳化（LTO），但在 macOS、iOS 或使用 MSVC 的 Windows 則會關閉 LTO，因為這些平台 LTO 連結速度較慢，或可能導致產生的程式碼有問題。

你也可以在同一指令列上以不同值指定這些選項來手動覆寫別名內容。例如可用 scons production=yes debug_symbols=yes 來產生包含偵錯符號的發行版最佳化執行檔。

開發建置

備註

dev_build 不要 和 dev_mode 混淆，後者是多個開發相關選項的合成別名（見上）。

在進行引擎開發時，可以搭配 target 使用 dev_build 選項，來啟用開發專用程式碼。dev_build 會定義 DEV_ENABLED、停用最佳化（-O0//0d）、啟用產生偵錯符號，並且不定義 NDEBUG``（讓 ``assert() 能在第三方函式庫中正常運作）。

scons platform=<platform> dev_build=yes

此選項會讓產生的執行檔名稱加上 .dev 後綴（代表開發用）。

也參考

SCons 還有其他選項可啟用 sanitizer 工具，這些工具能於編譯階段協助你偵錯特定的引擎問題。詳情請參考 使用 Sanitizer 。

偵錯符號

預設會使用 debug_symbols=no，也就是編譯後的執行檔**不會**包含偵錯符號。若要在執行檔中包含偵錯符號，請使用 debug_symbols=yes，這能讓偵錯器和效能分析工具正常運作，Godot 的當機堆疊追蹤也需要偵錯符號才能顯示出原始碼檔案與行號的資訊。

缺點是偵錯符號通常非常大（甚至比執行檔本身還大）。因此官方釋出的執行檔並不包含偵錯符號。如需偵錯符號，需自行編譯 Godot。

在使用 debug_symbols=yes 時，也可加上 separate_debug_symbols=yes，將偵錯資訊存到副檔名為 .debug 的獨立檔案，方便分開發布。注意，在 Windows 上用 MSVC 編譯時，偵錯資訊*永遠*會寫到獨立的 .pdb 檔，不受 separate_debug_symbols 是否啟用影響。

小訣竅

若要移除已編譯執行檔的偵錯符號，可使用 strip <binary檔路徑> 指令。

最佳化等級

可選擇以下幾種編譯器最佳化等級：

  • optimize=speed_trace （非 Web 平台的預設值）：以提升執行速度為主，犧牲二進位大小。部分最佳化可能會影響偵錯器的可用性（如堆疊追蹤不夠精確）。若遇此狀況，建議改用 optimize=debug。

  • optimize=speed：進一步提升執行速度，二進位檔更大。比 optimize=debug 更不利於偵錯，因為會啟用最激進的最佳化選項。

  • optimize=size （Web 平台預設值）：優先減小執行檔大小，但執行速度較慢。

  • optimize=size_extra：比 optimize=size 產生更小的二進位檔，但執行速度會更慢。

  • optimize=debug：僅啟用對偵錯無影響的最佳化，執行檔速度快於 optimize=none，但慢於 optimize=speed_trace。

  • optimize=none：完全不進行最佳化。建置最快，但執行效能最差。

  • optimize=custom （僅限進階用戶）：不自動將最佳化參數傳給 C/C++ 編譯器，你需要自行以 cflags、ccflags 和 cxxflags SCons 選項手動設定相關參數。

架構

arch 選項用來指定執行檔要支援的 CPU 架構或系統版本。主要用於桌面平台，其他平台通常會被忽略。

arch 支援的值有：auto、x86_32、x86_64、arm32、arm64、rv64、ppc32、ppc64、wasm32。

scons platform=<platform> arch={auto|x86_32|x86_64|arm32|arm64|rv64|ppc32|ppc64|wasm32}

此選項會在產生的執行檔名稱後加上對應的 arch 字串。預設為 arch=auto，會自動偵測與主機相符的架構。

自訂模組

除了編譯內建模組外，亦可同時編譯位於 Godot 專案目錄外的自訂模組。

可於編譯時在指令列加入 custom_modules 選項。該選項接受以逗號分隔的多個路徑，路徑內可包含自訂的獨立 C++ 模組（與內建 modules/ 目錄類似）。

例如，你可同時指定相對路徑、絕對路徑或家目錄的自訂模組路徑：

scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules"

備註

若自訂模組資料夾名稱與內建模組相同，則編譯時只會包含自訂模組。可利用此機制覆寫內建模組的實作。

也參考

以 C++ 自訂模組

清理產生檔案

有時可能因先前產生的檔案造成錯誤。可用 scons --clean <選項> 指令（<選項>需與之前建置 Godot 時使用的參數相同）來清除。

你也可以使用 git clean -fixd，這會清理所有平台與組態的建置產物。注意，此指令會刪除版本庫中所有未追蹤及被忽略的檔案。若有未提交的變更，請勿執行！

其他建置選項

還有許多其他建置選項可用來調整 Godot 的建置方式（如指定編譯器、除錯選項等），以及要啟用或禁用的功能。

欲瞭解每個版本支援的所有選項，請檢查 scons --help 的輸出說明。

覆寫建置選項

使用設定檔

你可以在 Godot Engine 原始碼根目錄建立 custom.py 檔案，以初始化任何 SCons 建置選項（如同指令列設定）：

custom.py
optimize = "size"
module_mono_enabled = "yes"
use_llvm = "yes"
extra_suffix = "game_title"

你也可以在建置前停用部分內建模組，以縮短建置時間。詳見 最佳化建置檔案大小。

也參考

你可以使用線上工具 Godot build options generator 來產生包含 SCons 選項的 custom.py 檔案，並將其存放於 Godot 原始碼根目錄。

也可以透過 profile 指令列選項，明確指定其他自訂設定檔，兩者皆會覆寫預設建置組態：

scons profile=path/to/custom.py

備註

透過設定檔指定的建置選項，可再用指令列選項進行覆寫。

亦可根據條件覆寫選項：

custom.py
import version

# Override options specific for Godot 3.x and 4.x versions.
if version.major == 3:
    pass
elif version.major == 4:
    pass

使用 SCONSFLAGS 環境變數

SCONSFLAGS 是 SCons 使用的環境變數，可以自動設定建置選項，無需每次在指令列輸入。

舉例來說，你可以用上述 -j 選項強制所有建置都使用指定數目的 CPU 執行緒：

export SCONSFLAGS="-j4"

SCU（單一編譯單元）建置

傳統建置方式因每個編譯單元需包含大量標頭檔，常造成瓶頸。為了加速開發流程（而非發行建置），Godot 提供「單一編譯單元」建置（又稱 Unity/Jumbo build）。

啟用此選項後，指定資料夾內多個 .cpp 檔案會合併為單一編譯單元，標頭檔可多檔共用，大幅縮短建置時間。

要啟用 SCU 建置，請加上 scu_build=yes SCons 選項。

備註

若在開發 Pull Request 時使用 SCU 建置，務必在提交 PR 前進行一次傳統建置。因為 SCU 會共用先前 .cpp 檔的標頭，可能漏掉傳統建置會出錯的 include。雖然 CI 會檢查這些錯誤，但在本地提前發現會更有效率。

匯出樣板

官方匯出樣板可以從 Godot Engine 網站進行下載: godotengine.org 。但你也可以自行進行建置 (例如當需要新版本、使用自定模組、或是不信任其他人建置的版本時)。

若下載官方匯出模板套件並解壓縮後，可以注意到大多數檔案都是為各個平台最佳化過的二進位檔或套件：

android_debug.apk
android_release.apk
android_source.zip
ios.zip
linux_debug.arm32
linux_debug.arm64
linux_debug.x86_32
linux_debug.x86_64
linux_release.arm32
linux_release.arm64
linux_release.x86_32
linux_release.x86_64
macos.zip
version.txt
web_debug.zip
web_dlink_debug.zip
web_dlink_nothreads_debug.zip
web_dlink_nothreads_release.zip
web_dlink_release.zip
web_nothreads_debug.zip
web_nothreads_release.zip
web_release.zip
windows_debug_x86_32_console.exe
windows_debug_x86_32.exe
windows_debug_x86_64_console.exe
windows_debug_x86_64.exe
windows_debug_arm64_console.exe
windows_debug_arm64.exe
windows_release_x86_32_console.exe
windows_release_x86_32.exe
windows_release_x86_64_console.exe
windows_release_x86_64.exe
windows_release_arm64_console.exe
windows_release_arm64.exe

若要自己進行建置，請依照個別平台教學中的詳細說明來進行。各個平台的說明文件中都解釋了如何建置樣板。

The version.txt file should contain the corresponding Godot version identifier. This file is used to install export templates in a version-specific directory to avoid conflicts. For instance, if you are building export templates for Godot 4.4.1, version.txt should contain 4.4.1.stable on the first line (and nothing else). This version identifier is based on the major, minor, patch (if present) and status lines of the version.py file in the Godot Git repository.

如果您正在為多個平台開發，macOS 無疑是最方便的交叉編譯宿主平台，因為您可以為每個目標進行交叉編譯。Linux 和 Windows 次之，但 Linux 的優勢在於其設定更為容易。