为 Windows 平台编译

参见

本页面描述的是如何从源码编译 Windows 编辑器和导出模板二进制文件。如果你想要将项目导出到 Windows，请移步《为 Windows 导出》。

需求

要在Windows下进行编译, 需要以下内容:

  • A C++ compiler. Use one of the following:

    • Visual Studio Community, version 2019 or later. Visual Studio 2022 is recommended. Make sure to enable C++ in the list of workflows to install. 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.

    • MinGW-w64 with GCC can be used as an alternative to Visual Studio. Be sure to install/configure it to use the posix thread model. Important: When using MinGW to compile the master branch, you need GCC 9 or later. Supports x86_64 and x86_32 only.

    • MinGW-LLVM with clang can be used as an alternative to Visual Studio and MinGW-w64. Supports x86_64, x86_32, and arm64.

  • Python 3.8+. Make sure to enable the option to add Python to the PATH in the installer.

  • SCons 4.0+ 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).

备注

If you have Scoop installed, you can easily install MinGW and other dependencies using the following command:

scoop install python mingw

Scons will still need to be installed via pip

备注

If you have MSYS2 installed, you can easily install MinGW and other dependencies using the following command:

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

对于每个 MSYS2 MinGW 子系统，你应该在其 shell 中运行 pip3 install scons。

参见

To get the Godot source code for compiling, see 获取源代码.

For a general overview of SCons usage for Godot, see 构建系统介绍.

设置 SCons

To install SCons, open the command prompt and run the following command:

python -m pip install scons

如果你看到提示信息 Defaulting to user installation because normal site-packages is not writeable，那么你就需要提升权限后再重新执行该命令。使用管理员身份打开一个新的命令提示符，然后再执行该命令，确保 SCons 可以通过 PATH 访问。

要检查是否已正确安装Python和SCons, 可以在命令提示符 (cmd.exe) 中键入 python --version 和 scons --version.

如果上面的命令不起作用, 请确保在安装后将Python添加到 PATH 环境变量中, 然后再次检查. 为此, 你可以再次运行Python安装程序并启用将Python添加到 PATH 的选项.

如果 SCons 无法检测到你的 Visual Studio 安装，可能是因为你的 SCons 版本太老了。请使用 python -m pip install --upgrade scons 将其更新为最新版本。

下载 Godot 的源代码

详细步骤请参考 获取源代码。

从现在开始，本教程将假设你将源代码放在了 C:\godot。

警告

为了防止编译过程中由于连续病毒扫描而导致的速度减慢，请将 Godot 源文件夹添加到杀毒软件中的例外列表中。

For Windows Defender, hit the Windows key, type "Windows Security" then hit Enter. Click on Virus & threat protection on the left panel. Under Virus & threat protection settings click on Manage Settings and scroll down to Exclusions. Click Add or remove exclusions then add the Godot source folder.

编译

选择编译器

SCons will automatically find and use an existing Visual Studio installation. If you do not have Visual Studio installed, it will attempt to use MinGW instead. If you already have Visual Studio installed and want to use MinGW-w64, pass use_mingw=yes to the SCons command line. Note that MSVC builds cannot be performed from the MSYS2 or MinGW shells. Use either cmd.exe or PowerShell instead. If you are using MinGW-LLVM, pass both use_mingw=yes and use_llvm=yes to the SCons command line.

小技巧

During development, using the Visual Studio compiler is usually a better idea, as it links the Godot binary much faster than MinGW. However, MinGW can produce more optimized binaries using link-time optimization (see below), making it a better choice for production use. This is particularly the case for the GDScript VM which performs much better with MinGW compared to MSVC. Therefore, it's recommended to use MinGW to produce builds that you distribute to players.

All official Godot binaries are built in custom containers using MinGW.

运行 SCons

After opening a command prompt, change to the root directory of the engine source code (using cd) and type:

C:\godot> scons platform=windows

备注

使用多个 CPU 线程进行编译时，SCons 可能会警告 pywin32 丢失。你可以放心地忽略此警告。

小技巧

If you are compiling Godot to make changes or contribute to the engine, you may want to use the SCons options dev_build=yes or dev_mode=yes. See 开发别名与生产别名 for more info.

If all goes well, the resulting binary executable will be placed in C:\godot\bin\ with the name godot.windows.editor.x86_32.exe or godot.windows.editor.x86_64.exe. By default, SCons will build a binary matching your CPU architecture, but this can be overridden using arch=x86_64, arch=x86_32, or arch=arm64.

该可执行文件包含整个引擎，并且运行时没有任何依赖项。运行它会启动项目管理器。

小技巧

If you are compiling Godot for production use, you can make the final executable smaller and faster by adding the SCons option production=yes. This enables additional compiler optimizations and link-time optimization.

LTO takes some time to run and requires up to 30 GB of available RAM while compiling (depending on toolchain). If you're running out of memory with the above option, use production=yes lto=none or production=yes lto=thin (LLVM only) for a lightweight but less effective form of LTO.

备注

如果你想为自己的 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.

You can find the detailed steps below if you wish to set up dependencies manually, but the above script handles everything for you (including the optional PIX and Agility SDK components).

  • godot-nir-static 库。我们将所需的 Mesa 库编译成了静态库。下载完成后将其解压，记下解压后得到的文件夹的路径，后面会用到。

备注

你也可以自行构建 godot-nir-static 库，方法如下：

  1. 安装 Python 包 mako，用于生成部分文件。

  2. 克隆 godot-nir-static 目录并打开。

  3. Run the following:

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 is a performance tuning and debugging application for Direct3D12 applications. If you compile-in support for it, you can get much more detailed information through PIX that will help you optimize your game and troubleshoot graphics bugs. To use it, download the WinPixEventRuntime package. You will be taken to a NuGet package page where you can click "Download package" to get it. Once downloaded, change the file extension to .zip and unzip the file to some path.

  • Agility SDK can be used to provide access to the latest Direct3D 12 features without relying on driver updates. To use it, download the latest Agility SDK package. You will be taken to a NuGet package page where you can click "Download package" to get it. Once downloaded, change the file extension to .zip and unzip the file to some path.

备注

If you use a preview version of the Agility SDK, remember to enable developer mode in Windows; otherwise it won't be used.

备注

If you want to use a PIX with MinGW build, navigate to PIX runtime directory and use the following commands to generate 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.

By default, Godot is built with AccessKit dynamically linked. You can use it by placing accesskit.dll alongside the executable.

备注

You can use dynamically linked AccessKit with export templates as well, rename the DLL to accesskit.{architecture}.dll and place them alongside the export template executables, and the libraries will be automatically copied during the export process.

To compile Godot with statically linked AccessKit:

  • Download the pre-built static libraries from godot-accesskit-c-static library, and unzip them.

  • When building Godot, add accesskit_sdk_path={path} to tell SCons where to look for the AccessKit libraries:

    scons platform=windows accesskit_sdk_path=<...>

备注

You can optionally build the godot-angle-static libraries yourself with the following steps:

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

  2. Run the following command:

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.

编译时启用 ANGLE 支持

ANGLE provides a translation layer from OpenGL ES 3.x to Direct3D 11 and can be used to improve support for the Compatibility renderer on some older GPUs with outdated OpenGL drivers and on Windows for ARM.

By default, Godot is built with dynamically linked ANGLE, you can use it by placing libEGL.dll and libGLESv2.dll alongside the executable.

备注

You can use dynamically linked ANGLE with export templates as well, rename the DLLs to libEGL.{architecture}.dll and libGLESv2.{architecture}.dll and place them alongside the export template executables, and the libraries will be automatically copied during the export process.

To compile Godot with statically linked ANGLE:

  • Download the pre-built static libraries from godot-angle-static library, and unzip them.

  • When building Godot, add angle_libs={path} to tell SCons where to look for the ANGLE libraries:

    scons platform=windows angle_libs=<...>

备注

You can optionally build the godot-angle-static libraries yourself with the following steps:

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

  2. Run the following command:

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.

在 Visual Studio 中进行开发

编译 Godot 不需要使用 IDE，SCons 会处理所有事情。但是如果你想要做引擎开发，或者调试引擎的 C++ 代码，你可能会对配置代码编辑器或者 IDE 感兴趣。

基于文件夹的编辑器不需要任何特殊的设置就可以开始使用 Godot 的代码库。要使用 Visual Studio 来编辑项目，需要先设置解决方案。

You can create a Visual Studio solution via SCons by running SCons with the vsproj=yes parameter, like this:

scons platform=windows vsproj=yes

你现在可以在 Visual Studio 解决方案中打开 Godot 的源代码，并能够通过 Visual Studio 的构建按钮构建 Godot。

参见

详见 Visual Studio。

故障排除

如果使用 MSVC 时遇到编译失败，请确保已安装最新更新。您可以通过启动 Visual Studio IDE，点击 Continue without code`（无代码继续），然后在顶部菜单栏中选择 :menu:`Help > Check for Updates （帮助 > 检查更新）来完成更新。安装所有更新后，再次尝试编译。

从其他操作系统为 Windows 交叉编译

If you are a Linux or macOS user, you need to install MinGW-w64, which typically comes in 32-bit and 64-bit variants, or MinGW-LLVM, which comes as a single archive for all target architectures. The package names may differ based on your distribution, here are some known ones:

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

Before attempting the compilation, SCons will check for the following binaries in your PATH environment variable:

# 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

If the binaries are not located in the PATH (e.g. /usr/bin), you can define the following environment variable to give a hint to the build system:

export MINGW_PREFIX="/path/to/mingw"

Where /path/to/mingw is the path containing the bin directory where i686-w64-mingw32-gcc and x86_64-w64-mingw32-gcc are located (e.g. /opt/mingw-w64 if the binaries are located in /opt/mingw-w64/bin).

To make sure you are doing things correctly, executing the following in the shell should result in a working compiler (the version output may differ based on your system):

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

备注

If you are building with MinGW-LLVM, add use_llvm=yes to the scons command.

备注

When cross-compiling for Windows using MinGW-w64, keep in mind only x86_64 and x86_32 architectures are supported. MinGW-LLVM supports arm64 as well. Be sure to specify the right arch= option when invoking SCons if building from a different architecture.

故障排除

由于默认配置不支持POSIX线程, 因此从某些Ubuntu版本进行交叉编译可能会导致 此bug .

You can change that configuration following those instructions, for 64-bit:

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>

And for 32-bit:

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 export templates are created by compiling Godot without the editor, with the following flags:

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

If you plan on replacing the standard export templates, copy these to the following location, replacing <version> with the version identifier (such as 4.2.1.stable or 4.3.dev):

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

With the following names:

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

However, if you are using custom modules or custom engine code, you may instead want to configure your binaries as custom export templates in the project export menu. You must have Advanced Options enabled to set this.

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

在这种情况下, 你不需要复制它们, 只需引用在Godot源文件夹的 bin\ 目录中生成的文件, 因此下次构建时, 将自动引用自定义模板.