在 Windows 上編譯

也參考

本頁說明如何從原始碼編譯 Windows 編輯器與匯出範本二進位檔。若你想要將專案匯出到 Windows，請參閱 為 Windows 匯出。

系統需求

在 Windows 下編譯需要下列條件：

  • 需要一個 C++ 編譯器，請選擇以下其中一種：

    • Visual Studio Community，2019 或更新版本。建議使用 Visual Studio 2022。請務必在安裝流程中勾選 C++ 支援。 若你已經安裝了 Visual Studio 但沒有 C++ 支援，請重新執行安裝程式並點選 Modify 按鈕。支援 x86_64、x86_32 和 arm64 架構。

    • 也可以使用配有 GCC 的 MinGW-w64 來取代 Visual Studio。請確保安裝或設定時選用 posix 執行緒模型。重要： 若要用 MinGW 編譯 master 分支，需使用 GCC 9 或更新版本。僅支援 x86_64 與 x86_32 架構。

    • 也可使用配有 clang 的 MinGW-LLVM 來取代 Visual Studio 與 MinGW-w64。支援 x86_64、x86_32 與 arm64 架構。

  • Python 3.8+。請記得在安裝程式中勾選「將 Python 加入 ``PATH``」的選項。

  • SCons 4.0+ 建構系統。建議使用最新版，才能正確支援最新的 Visual Studio。

備註

若有安裝 Scoop，可用下列指令輕鬆安裝 MinGW 及其他相依套件：

scoop install python mingw

Scons will still need to be installed via pip

備註

若有安裝 MSYS2，可用下列指令輕鬆安裝 MinGW 及其他相依套件：

pacman -S mingw-w64-x86_64-python3-pip mingw-w64-x86_64-gcc  \
    mingw-w64-i686-python3-pip mingw-w64-i686-gcc make

需在每個 MSYS2 MinGW 子系統的 Shell 中執行 pip3 install scons。

也參考

如需取得 Godot 編譯所需的原始碼，請參閱 取得原始碼。

關於 Godot 使用 SCons 的基本說明，請參閱 建置系統介紹。

設定 SCons

要安裝 SCons，請開啟命令提示字元並輸入下列指令：

python -m pip install scons

若看到 Defaulting to user installation because normal site-packages is not writeable 訊息，請以系統管理員身分重新開啟命令提示字元並再次執行該指令，以確保 SCons 能在 PATH 中使用。

可於命令提示字元（cmd.exe）輸入 python --version 與 scons --version 來檢查 Python 與 SCons 是否安裝正確。

如果上述指令無法執行，請確認安裝 Python 後已將其加入 PATH 環境變數，再重新檢查。可再次執行 Python 安裝程式並勾選「將 Python 加入 PATH」選項。

若 SCons 無法偵測你的 Visual Studio 安裝，可能是 SCons 版本過舊，請用 python -m pip install --upgrade scons 升級至最新版。

下載 Godot 原始碼

詳情請參閱 取得原始碼。

本教學接下來預設你的原始碼放在 C:\godot。

警告

為避免在編譯時因為殺毒軟體持續掃描導致速度變慢，請將 Godot 原始碼資料夾加入防毒軟體的例外清單。

對於 Windows Defender，請按下 Windows 鍵，輸入「Windows 安全性」並按 Enter。點選左側的 病毒與威脅防護。在 病毒與威脅防護設定 下，點擊 管理設定 並捲動到 排除項目。點選 新增或移除排除項目，然後新增 Godot 原始碼資料夾。

編譯

選擇編譯器

SCons 會自動搜尋並使用已安裝的 Visual Studio。如果你沒有安裝 Visual Studio，SCons 會改用 MinGW。若已安裝 Visual Studio 但想用 MinGW-w64，請在 SCons 命令列加上 use_mingw=yes。注意：MSVC 編譯無法在 MSYS2 或 MinGW shell 下進行，請改用 cmd.exe 或 PowerShell。如果要用 MinGW-LLVM，請同時加上 use_mingw=yes 與 use_llvm=yes。

小訣竅

開發期間，建議使用 Visual Studio 編譯器，因為它連結 Godot 二進位檔的速度比 MinGW 快很多。但 MinGW 支援連結時最佳化（LTO，見下方），可生成更高效的二進位檔，適合正式發行版本。特別是在 GDScript VM 部分，使用 MinGW 的效能會比 MSVC 好許多。因此，建議用 MinGW 編譯要發佈給玩家的版本。

Godot 官方所有二進位檔皆是在 專用容器 以 MinGW 編譯產生。

執行 SCons

開啟命令提示字元後，請（用 cd）切換到引擎原始碼的根目錄，然後輸入：

C:\godot> scons platform=windows

備註

如果用多核心執行緒編譯，SCons 可能會提示找不到 pywin32，可以放心忽略這個警告。

小訣竅

若你自行編譯 Godot 以進行修改或貢獻開發，建議在 SCons 加上 dev_build=yes 或 dev_mode=yes 選項。詳情請參閱 開發與發行別名。

編譯完成後，產生的執行檔會放在 C:\godot\bin\，檔名為 godot.windows.editor.x86_32.exe 或 godot.windows.editor.x86_64.exe。預設 SCons 會自動偵測並建構符合你 CPU 架構的二進位檔，也可用 arch=x86_64、arch=x86_32 或 arch=arm64 來指定。

此執行檔包含完整引擎，無其他相依檔案，啟動後會進入專案管理員。

小訣竅

若要為正式發行版本編譯 Godot，可加上 SCons 選項 production=yes，讓最終執行檔更精簡且速度更快。此選項會啟用進階編譯器最佳化與連結時最佳化（LTO）。

LTO（連結時最佳化）會延長編譯時間，且需高達 30GB 記憶體（視工具鏈而異）。若記憶體不足，可用 production=yes lto=none 或（僅限 LLVM）用 production=yes lto=thin，這樣會使用較少資源但最佳化效果較低。

備註

若希望自編譯 Godot 和官方版本使用不同編輯器設定，可在 bin/ 資料夾內建立 ._sc_ 或 _sc_ 檔案，以啟用 自包含模式。

編譯支援 Direct3D 12

預設情況下，Godot 並未內建支援 Direct3D 12 圖形 API。

你可以在 Godot 原始碼資料夾中執行 python misc/scripts/install_d3d12_sdk_windows.py 來安裝所需相依套件。執行完畢後，在 SCons 命令加上 d3d12=yes 參數即可啟用 Direct3D 12 支援。這會自動使用與腳本一致的預設相依套件路徑。

若你想手動安裝相依套件，下方會有詳細步驟，但上述腳本已會自動處理（包含選用的 PIX 與 Agility SDK 元件）。

  • godot-nir-static library。我們已將所需的 Mesa 函式庫編譯成靜態函式庫。請下載後解壓縮，並記下路徑，後續會用到。

備註

你也可依下列步驟自行編譯 godot-nir-static 函式庫：

  1. 安裝 Python 套件 mako，這是用來產生部分檔案所需。

  2. 複製 godot-nir-static 專案並切換到該資料夾。

  3. 執行下列指令：

    git submodule update --init
./update_mesa.sh
scons

    若用 MinGW-w64 編譯，請於 scons 指令加上 use_mingw=yes，並可用 arch={architecture} 指定架構。若用 MinGW-LLVM，請同時加上 use_mingw=yes 與 use_llvm=yes。

    若用 MinGW 編譯且執行檔不在 PATH，請於 scons 指令加上 mingw_prefix="/path/to/mingw"。

    Mesa 靜態函式庫必須使用與你編譯 Godot 相同的編譯器與 CRT（C 執行期庫，若用 MinGW 時）。

你也可以加上以下功能進行編譯：

  • PIX 是針對 Direct3D12 應用的效能調校與偵錯工具。若你編譯時加入其支援，可藉由 PIX 取得更詳細資訊，協助優化遊戲與偵錯圖形問題。使用方法：下載 WinPixEventRuntime 套件（會導向 NuGet 網頁，點選「Download package」），下載後將副檔名改為 .zip 並解壓縮。

  • Agility SDK 可讓你不需依賴顯示卡驅動程式更新也能用到最新的 Direct3D 12 功能。使用方法：下載最新版 Agility SDK 套件（同樣會導向 NuGet，點選「Download package」），下載後將副檔名改為 .zip 並解壓縮。

備註

若使用 Agility SDK 預覽版，請記得在 Windows 啟用開發人員模式，否則無法套用。

備註

若要在 MinGW 編譯版本中啟用 PIX，請切換至 PIX 執行時目錄並執行下列指令以產生 import library：

# For x86-64:
gendef ./bin/x64/WinPixEventRuntime.dll
dlltool --machine i386:x86-64 --no-leading-underscore -d WinPixEventRuntime.def -D WinPixEventRuntime.dll -l ./bin/x64/libWinPixEventRuntime.a

# For ARM64:
gendef ./bin/ARM64/WinPixEventRuntime.dll
dlltool --machine arm64 --no-leading-underscore -d WinPixEventRuntime.def -D WinPixEventRuntime.dll -l ./bin/ARM64/libWinPixEventRuntime.a

編譯 Godot 時，需指定 SCons 啟用 Direct3D 12，並告知相依函式庫路徑：

C:\godot> scons platform=windows d3d12=yes mesa_libs=<...>

或啟用全部選項時：

C:\godot> scons platform=windows d3d12=yes mesa_libs=<...> agility_sdk_path=<...> pix_path=<...>

備註

Agility SDK 的 DLL 需選擇作業模式。預設為單一架構（DLL 複製到 bin/）。若在 SCons 加上 agility_sdk_multi_arch=yes 則會轉為多架構模式，DLL 會自動複製到 bin/<arch>/ 子目錄並於執行時自動載入正確版本。

編譯支援 ANGLE

ANGLE 提供 OpenGL ES 3.x 到 Direct3D 11 的轉換層，可提升部分舊型顯示卡（OpenGL 驅動程式較舊）及 Windows on ARM 上的相容性渲染器支援。

Godot 預設會使用動態連結的 ANGLE，只要將 libEGL.dll 與 libGLESv2.dll 放在執行檔旁即可。

備註

你也可以在匯出樣板中使用動態連結 ANGLE，將上述 DLL 檔案分別重新命名為 libEGL.{architecture}.dll 與 libGLESv2.{architecture}.dll 並放在匯出樣板執行檔旁，匯出時系統會自動複製所需函式庫。

若要以靜態連結方式編譯 Godot 並支援 ANGLE：

  • 請從 godot-angle-static library 下載預編譯靜態函式庫並解壓縮。

  • 編譯 Godot 時，在 SCons 命令加上 angle_libs={path}，指定 ANGLE 函式庫路徑：

    scons platform=windows angle_libs=<...>

備註

你也可以依下列步驟自行編譯 godot-angle-static 靜態函式庫：

  1. 複製 godot-angle-static 專案並切換到該資料夾。

  2. 執行下列指令：

    git submodule update --init
./update_angle.sh
scons

    若用 MinGW 編譯，請加上 use_mingw=yes，也可用 arch={architecture} 指定架構。若用 MinGW-LLVM，請同時加上 use_mingw=yes 與 use_llvm=yes。

    若用 MinGW 編譯且執行檔不在 PATH，請於 scons 指令加上 mingw_prefix="/path/to/mingw"。

    ANGLE 靜態函式庫必須使用與 Godot 相同的編譯器及 C 執行期庫（CRT，若用 MinGW 時）編譯。

在 Visual Studio 進行開發

編譯 Godot 不一定要用 IDE，SCons 會自動處理。不過如果你打算開發或除錯引擎 C++ 原始碼，建議可以設定程式碼編輯器或 IDE。

資料夾型編輯器不需特殊設定即可開始瀏覽 Godot 原始碼。若要用 Visual Studio 編輯專案，需先建立解決方案。

可透過 SCons 加上 vsproj=yes 參數來產生 Visual Studio 解決方案，例如：

scons platform=windows vsproj=yes

之後即可在 Visual Studio 解決方案中開啟 Godot 原始碼，並使用 建置 按鈕直接編譯。

也參考

詳情請參閱 Visual Studio。

在其他作業系統上交叉編譯 Windows 版本

若你是 Linux 或 macOS 使用者，需安裝 MinGW-w64 （通常有 32 位元與 64 位元版本），或 MinGW-LLVM （單一壓縮檔支援所有目標架構）。不同套件管理系統名稱可能不同，以下列出部分常見名稱：

Arch Linux

 
pacman -Sy mingw-w64

Debian / Ubuntu

 
apt install mingw-w64

Fedora

 
dnf install mingw64-gcc-c++ mingw64-winpthreads-static \
            mingw32-gcc-c++ mingw32-winpthreads-static

macOS

 
brew install mingw-w64

Mageia

 
urpmi mingw64-gcc-c++ mingw64-winpthreads-static \
      mingw32-gcc-c++ mingw32-winpthreads-static

在開始編譯前，SCons 會檢查這些執行檔是否已在你的 PATH 環境變數中：

# for MinGW-w64
i686-w64-mingw32-gcc
x86_64-w64-mingw32-gcc

# for MinGW-LLVM
aarch64-w64-mingw32-clang
i686-w64-mingw32-clang
x86_64-w64-mingw32-clang

若這些執行檔不在 PATH``（例如 ``/usr/bin）中，可以定義下列環境變數讓建構系統找到：

export MINGW_PREFIX="/path/to/mingw"

其中 /path/to/mingw 應為包含 bin 資料夾的路徑，該資料夾內應有 i686-w64-mingw32-gcc 及 x86_64-w64-mingw32-gcc``（例如檔案在 ``/opt/mingw-w64/bin 時請設為 /opt/mingw-w64）。

為確認設定正確，可在 shell 執行下列指令，若有正確顯示版本號即表示可用（版本號會依系統不同而不同）：

${MINGW_PREFIX}/bin/x86_64-w64-mingw32-gcc --version
# x86_64-w64-mingw32-gcc (GCC) 13.2.0

備註

若用 MinGW-LLVM 編譯，請在 scons 指令中加上 use_llvm=yes。

備註

使用 MinGW-w64 交叉編譯 Windows 時，僅支援 x86_64 與 x86_32 架構。若用 MinGW-LLVM，亦支援 arm64。如交叉編譯，請用 arch= 指定正確架構。

疑難排解

在某些 Ubuntu 版本上交叉編譯時，可能會因預設未支援 POSIX 執行緒而遇到 這個 bug。

可依照下列指示修改該設定（64 位元）：

sudo update-alternatives --config x86_64-w64-mingw32-gcc
<choose x86_64-w64-mingw32-gcc-posix from the list>
sudo update-alternatives --config x86_64-w64-mingw32-g++
<choose x86_64-w64-mingw32-g++-posix from the list>

32 位元則：

sudo update-alternatives --config i686-w64-mingw32-gcc
<choose i686-w64-mingw32-gcc-posix from the list>
sudo update-alternatives --config i686-w64-mingw32-g++
<choose i686-w64-mingw32-g++-posix from the list>

建立 Windows 匯出樣板

Windows 匯出樣板需使用下列旗標編譯不含編輯器的 Godot：

C:\godot> scons platform=windows target=template_debug arch=x86_32
C:\godot> scons platform=windows target=template_release arch=x86_32
C:\godot> scons platform=windows target=template_debug arch=x86_64
C:\godot> scons platform=windows target=template_release arch=x86_64
C:\godot> scons platform=windows target=template_debug arch=arm64
C:\godot> scons platform=windows target=template_release arch=arm64

如欲取代內建匯出樣板，請將這些檔案複製到下列位置，並將 <version> 替換為版本識別（如 4.2.1.stable 或 4.3.dev）：

%APPDATA%\Godot\export_templates\<version>\

檔名如下：

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

但如果使用自訂模組或自訂引擎原始碼，可在此設定自訂的匯出樣板：

../../../_images/wintemplates.webp

請在匯出設定中選擇相符的架構。

這種情況下不用複製檔案，只需在 Godot 原始碼的 bin\ 資料夾中直接參照產生的檔案即可，下次編譯會自動使用自訂樣板。