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...

在 Windows 上編譯

也參考

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

系統需求

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

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

    • Visual Studio Community, version 2019 or later. Visual Studio 2022 is recommended. Make sure to enable C++ in the list of workflows to install. Make sure to enable Windows SDK 10.0.22621 (for Visual Studio 2019) or more recent version (for Visual Studio 2022+). If you've already installed Visual Studio without C++ support, run the installer again; it should present you a Modify button. Supports x86_64, x86_32, and 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.9+. Make sure to enable the option to add Python to the PATH in the installer.

  • SCons 4.4+ build system. Using the latest release is recommended, especially for proper support of recent Visual Studio releases.

  • Direct3D 12 dependencies (can be skipped with the d3d12=no SCons option if Direct3D 12 support is not desired).

備註

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

scoop install python mingw

SCons 仍需透過 pip 安裝

備註

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

pacman -S mingw-w64-x86_64-gcc mingw-w64-i686-gcc make python-pip

需在每個 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_ 檔案，以啟用 自包含模式。

Installing Direct3D 12 requirements

By default, Windows builds of Godot contain support for the Direct3D 12 graphics API. Compiling with Direct3D 12 support requires additional dependencies to be installed. If you wish to skip this step, you can use the d3d12=no SCons option; Vulkan and OpenGL support will remain available if you do so.

You can install the required dependencies by running python misc/scripts/install_d3d12_sdk_windows.py in the Godot source repository. After running this script, compile Godot as usual. This will use the default paths for the various dependencies, which match the ones used in the script.

若你想手動安裝相依套件，下方會有詳細步驟，但上述腳本已會自動處理（包含選用的 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

If you are building with MinGW-w64, add use_mingw=yes to the scons command, you can also specify the build architecture using arch={architecture}. If you are building with MinGW-LLVM, add both use_mingw=yes and use_llvm=yes to the scons command.

If you are building with MinGW and the binaries are not located in the PATH, add mingw_prefix="/path/to/mingw" to the scons command.

The Mesa static library should be built using the same compiler and the same CRT (if you are building with MinGW) you are using for building Godot.

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

  • 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

When building Godot, you will need to tell SCons where to look for the additional libraries:

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

或啟用全部選項時：

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

備註

PIX support is disabled by default, even if you have it installed. To enable it, pass use_pix=yes to SCons.

備註

For the Agility SDK's DLLs, you have to explicitly choose the kind of workflow. Single-arch is the default (DLLs copied to bin/). If you pass agility_sdk_multi_arch=yes to SCons, you'll opt-in for multi-arch. DLLs will be copied to the appropriate bin/<arch>/ subdirectories and at runtime, the right one will be loaded.

Compiling with AccessKit support

AccessKit provides support for screen readers.

Compiling with AccessKit requires additional dependencies to be installed. If you wish to skip this step, you can use the accesskit=no SCons option.

You can install the required dependencies by running python misc/scripts/install_accesskit.py in the Godot source repository. After running this script, compile Godot as usual.

備註

You can optionally build the AccessKit libraries yourself with the following steps:

  1. Clone the godot-accesskit-c-static directory and navigate to it.

  2. 執行下列指令：

cd accesskit-c
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build

The AccessKit static library should be built using the same compiler and the same CRT (if you are building with MinGW) you are using for building Godot.

To compile Godot with a custom build of AccessKit, add accesskit_sdk_path={path} to tell SCons where to look for the AccessKit libraries:

scons platform=windows accesskit_sdk_path=<...>

Compiling with WinRT support

WinRT provides support for OneCore TTS (accessing Windows 10+ voices), HDR color information monitoring, and emoji picker.

If you are building with MinGW, compiling with WinRT requires additional dependencies to be installed. If you wish to skip this step, you can use the winrt=no SCons option.

You can install the required dependencies by running python misc/scripts/install_winrt.py in the Godot source repository. After running this script, compile Godot as usual.

備註

You can optionally build the WinRT headers yourself with the following steps:

  1. Clone the winrt-mingw directory and navigate to it.

  2. 執行下列指令：

cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DCPPWINRT_BUILD_VERSION=2.0.250303.1 -DBUILD_TESTING=OFF cppwinrt/
echo "" > build/app.manifest.rc
cmake --build build
./build/cppwinrt.exe -input windows-rs/crates/libs/bindgen/default/ -output include/

To compile Godot with a custom build of WinRT, add winrt_path={path} to tell SCons where to look for the AccessKit headers:

scons platform=windows winrt_path=<...>

編譯支援 ANGLE

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

Compiling with ANGLE requires additional dependencies to be installed. If you wish to skip this step, you can use the angle=no SCons option.

You can install the required dependencies by running python misc/scripts/install_angle.py in the Godot source repository. After running this script, compile Godot as usual.

備註

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

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

  2. 執行下列指令：

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

If you are buildng with MinGW, add use_mingw=yes to the command, you can also specify the build architecture using arch={architecture}. If you are building with MinGW-LLVM, add both use_mingw=yes and use_llvm=yes to the scons command.

If you are building with MinGW and the binaries are not located in the PATH, add mingw_prefix="/path/to/mingw" to the scons command.

The ANGLE static library should be built using the same compiler and the same CRT (if you are building with MinGW) you are using for building Godot.

To compile Godot with a custom build of ANGLE, add angle_libs={path} to tell SCons where to look for the ANGLE libraries:

scons platform=windows angle_libs=<...>

在 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。

疑難排解

若使用 MSVC 編譯失敗，請先確認已套用最新更新。可啟動 Visual Studio IDE，點選 Continue without code，再從頂端選單的 Help > Check for Updates 檢查更新。安裝所有更新後再嘗試編譯。

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

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

Arch Linux

 
pacman -S 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

但如果你使用自訂模組或自訂引擎程式碼，則可在專案的匯出選單中將你的二進位檔設定為自訂匯出樣板。你必須啟用 Advanced Options（進階選項） 才能進行此設定。

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

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