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,版本要求為 2019 或更高版本(推薦使用 Visual Studio 2022)。 在安裝過程中,請務必在工作負載(workflows)清單中勾選“使用 C++ 的桌面開發”,並選擇以下獨立元件:
MSVC v142 - VS 2019 C++ {arch} build tools (Latest) 對於目標平台架構。
Windows 11 SDK (10.0.22621.0) (確切的版本)。
MSVC v143 - VS 2022 C++ {arch} build tools (Latest) 用於目標架構。
Windows 11 SDK (10.0.22621.0) 或更新。
MSVC Build Tools for {arch} (Latest) 用於目標架構。
Windows 11 SDK (10.0.22621.0) 或更新。
如果你之前安裝 Visual Studio 時沒有勾選針對目標架構的 C++ 支援,或者沒有安裝 Windows SDK,請重新執行安裝程式;此時介面應該會顯示一個 修改(Modify) 按鈕。目前支援的架構包括
x86_64,x86_32, 和arm64。MinGW-w64 配合 GCC 可以作為 Visual Studio 的替代方案。請務必確保安裝或設定時使用的是
posix執行緒模型。 重要提示: 如果使用 MinGW 來編譯master(主)分支,你需要 GCC 12 或更高版本。此外,該方案僅支援x86_64和x86_32架構。MinGW-LLVM 配合 Clang 也可以作為 Visual Studio 和 MinGW-w64 的替代方案。 重要提示: 如果使用 MinGW 來編譯
master(主)分支,你需要 Clang 14 或更高版本。該方案支援x86_64、x86_32和arm64架構。
Python 3.9+. 在安裝程式中 , 請務必勾選(或開啟)環境變數的選項將 Python 新增到
PATH如果使用 Python 3.9 至 3.13,還須執行
pip install --user zstandard,安裝 Python 的 Zstandard 支援。Python 3.14 及更新版本已預設包含 Zstandard 支援,因此不需要此步驟。
SCons 4.4+ 建置系統。建議使用最新的發佈版本,尤其是為了確保能良好支援近期的 Visual Studio 版本。
Direct3D 12 dependencies (如果你不需要 Direct3D 12 支援,可以通過在 SCons 命令中新增
d3d12=no選項來跳過安裝)。
備註
若有安裝 MSYS2,可用下列指令輕鬆安裝 MinGW 及其他相依套件:
pacman -S mingw-w64-x86_64-gcc mingw-w64-i686-gcc make python-pip
對於每個 MSYS2 MinGW 子系統,您應在其 shell 中執行 pip3 install 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 的相依項目(或者叫“安裝 Direct3D 12 所需的環境/要求”)
預設情況下,Godot 的 Windows 建置版本包含對 Direct3D 12 圖形 API 的支援。編譯帶有 Direct3D 12 支援的版本需要安裝額外的相依項目。如果你想跳過這一步,可以在 SCons 命令中使用 d3d12=no 選項;即使這樣做了,Vulkan 和 OpenGL 的支援依然會保留。
你可以通過在 Godot 原始碼倉庫中執行 python misc/scripts/install_d3d12_sdk_windows.py 來安裝所需的相依項目。執行此腳本後,照常編譯 Godot。這將使用各種相依項目的預設路徑,這些路徑與腳本中使用的路徑相匹配。
若你想手動安裝相依套件,下方會有詳細步驟,但上述腳本已會自動處理(包含選用的 PIX 與 Agility SDK 元件)。
godot-nir-static library。我們已將所需的 Mesa 函式庫編譯成靜態函式庫。請下載後解壓縮,並記下路徑,後續會用到。
備註
你也可依下列步驟自行編譯 godot-nir-static 函式庫:
安裝 Python 套件 mako,這是用來產生部分檔案所需。
複製 godot-nir-static 專案並切換到該資料夾。
執行下列指令:
git submodule update --init
./update_mesa.sh
scons
如果你使用的是 MinGW-w64 進行編譯,請在 scons 命令後面加上 use_mingw=yes 參數;你還可以通過 arch={architecture} 來指定編譯的目標架構。如果你使用的是 MinGW-LLVM 進行編譯,則需要在 scons 命令中同時加上 use_mingw=yes 和 use_llvm=yes 這兩個參數。
如果你正在使用 MinGW 進行編譯,而編譯器的二進位檔案(binaries)所在的目錄沒有被新增到系統的 PATH 環境變數中,請在 scons 命令後面加上 mingw_prefix="/path/to/mingw" 參數。
編譯 Mesa 靜態庫時,應該使用和你編譯 Godot 時完全相同的編譯器,以及相同的 CRT(如果你是用 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 去哪裡找這些額外的庫檔案:
C:\godot> scons platform=windows mesa_libs=<...>
或啟用全部選項時:
C:\godot> scons platform=windows mesa_libs=<...> agility_sdk_path=<...> pix_path=<...>
備註
PIX 支援預設是停用的,即使你已經安裝了它。如果要啟用它,請在 SCons 命令中加上 use_pix=yes 。
備註
對於 Agility SDK 的 DLL 檔案,你必須明確選擇使用哪種工作流程。預設是單架構(single-arch)模式(也就是把 DLL 檔案直接複製到 bin/ 目錄下)。如果你在 SCons 里加上了 agility_sdk_multi_arch=yes 這個參數,就會啟用多架構(multi-arch)模式。在這種模式下,DLL 檔案會被分別複製到對應的 bin/<arch>/ 子資料夾里,這樣在程式執行時,就會自動載入目前裝置架構對應的那個正確檔案啦。
編譯時啟用 AccessKit 支援
AccessKit 提供了對螢幕閱讀器的支援。
如果要編譯並集成 AccessKit 功能,需要先安裝額外的相依項目。如果你不想處理這些相依性(想跳過這一步),可以在使用 SCons 編譯時加上 accesskit=no 這個選項。
你可以在 Godot 原始碼倉庫中執行 python misc/scripts/install_accesskit.py 來安裝所需的相依項目。執行完這個腳本後,照常編譯 Godot 即可。
備註
你也可以選擇按照以下步驟,自己手動編譯 AccessKit 庫:
克隆(Clone) godot-accesskit-c-static 倉庫,然後進入該目錄。
執行下列指令:
cd accesskit-c
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build
編譯 AccessKit 靜態庫時,應該使用和你編譯 Godot 時完全相同的編譯器,以及相同的 CRT(如果你是用 MinGW 進行編譯的話)。
如果你要用自己編譯的 AccessKit 版本來編譯 Godot,需要加上 accesskit_sdk_path={path} 這個參數,用來告訴 SCons 去哪裡尋找 AccessKit 的庫檔案:
scons platform=windows accesskit_sdk_path=<...>
編譯支援 ANGLE
ANGLE 提供 OpenGL ES 3.x 到 Direct3D 11 的轉換層,可提升部分舊型顯示卡(OpenGL 驅動程式較舊)及 Windows on ARM 上的相容性渲染器支援。
使用 ANGLE 進行編譯需要安裝額外的相依項目。如果你想跳過這一步(不使用 ANGLE),可以在使用 SCons 編譯時加上 angle=no 這個選項。
你可以在 Godot 原始碼倉庫中執行 python misc/scripts/install_angle.py 來安裝所需的相依項目。執行完這個腳本後,照常編譯 Godot 即可。
備註
你也可以依下列步驟自行編譯 godot-angle-static 靜態函式庫:
複製 godot-angle-static 專案並切換到該資料夾。
執行下列指令:
git submodule update --init
./update_angle.sh
scons
如果你使用 MinGW 進行編譯,請在命令中加入 use_mingw=yes 參數;此外,你也可以通過 arch={architecture} 來指定編譯的目標架構。如果你使用的是 MinGW-LLVM 進行編譯,則需要在 scons 命令中同時加入 use_mingw=yes 和 use_llvm=yes 這兩個參數。
如果你正在使用 MinGW 進行編譯,而編譯器的二進位檔案(binaries)所在的目錄沒有被新增到系統的 PATH 環境變數中,請在 scons 命令後面加上 mingw_prefix="/path/to/mingw" 參數。
編譯 ANGLE 靜態庫時,應該使用和你編譯 Godot 時完全相同的編譯器,以及相同的 CRT(如果你是用 MinGW 進行編譯的話)。
如果你要用自己編譯的 ANGLE 版本來編譯 Godot,需要加上 angle_libs={path} 這個參數,用來告訴 SCons 去哪裡尋找 ANGLE 的庫檔案:
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,點選 ,再從頂端選單的 檢查更新。安裝所有更新後再嘗試編譯。
在其他作業系統上交叉編譯 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(進階選項) 才能進行此設定。
這種情況下不用複製檔案,只需在 Godot 原始碼的 bin\ 資料夾中直接參照產生的檔案即可,下次編譯會自動使用自訂樣板。