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. During installation make sure to select C++ in the list of workflows, and select the following individual components:

      • MSVC v142 - VS 2019 C++ {arch} build tools (Latest) for the target architectures.

      • Windows 11 SDK (10.0.22621.0) (exact version).

      If you've already installed Visual Studio without C++ support for the target architecture, or without the Windows SDK, 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 12 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. Important: When using MinGW to compile the master branch, you need clang 14 or later. Supports x86_64, x86_32, and arm64.

  • Python 3.9+. 在安装程序中 ， 请务必勾选（或开启）环境变量的选项将 Python 添加到 PATH

  • SCons 4.4+ 构建系统。建议使用最新的发布版本，尤其是为了确保能良好支持近期的 Visual Studio 版本。

  • Direct3D 12 dependencies （如果你不需要 Direct3D 12 支持，可以通过在 SCons 命令中添加 d3d12=no 选项来跳过安装）。

备注

如果你已经安装了`Scoop <https://scoop.sh/>`_，就可以轻松通过下面的命令来安装 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 访问。

要检查是否已正确安装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 源文件夹添加到杀毒软件中的例外列表中。

对于 Windows Defender，请按一下键盘上的e Windows 键，输入 "Windows Security（Windows 安全中心）" ，然后按t Enter 键打开。点击左侧面板上的 Virus & threat protection（病毒和威胁防护）。在 Virus & threat protection settings（病毒和威胁防护设置） 下方，点击 Manage Settings（管理设置） ，然后向下滚动找到 Exclusions（排除项） 。点击 Add or remove exclusions（添加或删除排除项） ，然后把 Godot 的源码文件夹添加进去即可。

编译

选择编译器

SCons 会自动查找并使用电脑上现有的 Visual Studio 安装。如果你没有安装 Visual Studio，它会尝试改用 MinGW。如果你已经安装了 Visual Studio，但依然想使用 MinGW-w64，请在 SCons 命令行中加入 use_mingw=yes 参数。需要注意的是，MSVC 编译不能在 MSYS2 或 MinGW 的终端（Shell）中进行，请使用 cmd.exe 或 PowerShell 代替。如果你使用的是 MinGW-LLVM，请在 SCons 命令行中同时加入 use_mingw=yes 和 use_llvm=yes 参数。

小技巧

在开发阶段，使用 Visual Studio 的编译器通常是更好的选择，因为它的链接速度比 MinGW 快得多（能省下不少等待时间）。不过，MinGW 能够利用链接时优化（Link-time Optimization，详见下文）生成优化程度更高的二进制文件，这使得它更适合用于生产环境。这一点在 GDScript 虚拟机上的表现尤为明显——它在 MinGW 下的运行效率要比在 MSVC 下高得多。因此，强烈建议你使用 MinGW 来编译最终分发给玩家的版本。

所有 Godot 的官方二进制文件（即正式发布的可执行程序），都是使用 MinGW 在 自定义的容器 中编译构建的。

运行 SCons

打开命令提示符（终端）后，先切换到引擎源代码的根目录（使用 cd 命令），然后输入：

C:\godot> scons platform=windows

备注

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

小技巧

如果你编译 Godot 是为了修改源码或者为引擎做贡献，那你可能会想使用 dev_build=yes 或 dev_mode=yes 这两个 SCons 选项。想了解更多的话，可以看看 开发别名与生产别名 。

如果一切顺利，编译好的二进制可执行文件就会出现在 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.

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

小技巧

如果你正在为正式发布（production use）而编译 Godot，可以通过添加 SCons 参数 production=yes 来让最终的执行程序变得更小、运行速度更快。这个参数会启用更多额外的编译器优化以及链接时优化（LTO）。

LTO 的运行需要花费一些时间，并且在编译期间需要高达 30 GB 的可用内存（具体取决于你使用的工具链）。如果你在使用上述选项时内存不足，可以使用 production=yes lto=none ，或者使用 production=yes lto=thin （仅限 LLVM）来采用一种更轻量级、但优化效果稍弱的 LTO 形式。

备注

如果你想为自己的 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 库。我们将所需的 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 进行编译，则需要在 scons 命令中同时加上 use_mingw=yes 和 use_llvm=yes 这两个参数。

如果你正在使用 MinGW 进行编译，而编译器的二进制文件（binaries）所在的目录没有被添加到系统的 PATH 环境变量中，请在 scons 命令后面加上 mingw_prefix="/path/to/mingw" 参数。

编译 Mesa 静态库时，应该使用和你编译 Godot 时完全相同的编译器，以及相同的 CRT（如果你是用 MinGW 进行编译的话）。

另外你还可以在编译时启用以下附加功能：

  • PIX 是一款专门针对 Direct3D12 应用程序的性能调优和调试工具。如果你在编译 Godot 时加入了它的支持，就能通过 PIX 获取更加详尽的信息，从而帮助你更好地优化游戏性能，并排查各种图形显示方面的 Bug。想要使用它，请下载 WinPixEventRuntime 这个包。页面会跳转到一个 NuGet 包的下载页，点击 "Download package" （下载包）即可获取。下载完成后，将文件的后缀名改为 .zip，然后把它解压到你指定的某个路径下。

  • 你可以使用 Agility SDK 来直接获取最新的 Direct3D 12 特性，而无需依赖显卡驱动程序的更新。要使用它，请下载最新的 Agility SDK 安装包。页面会跳转到一个 NuGet 包页面，点击 "Download package" （下载包）即可获取。下载完成后，将文件的后缀名改为 .zip，然后把它解压到你指定的某个路径下。

备注

如果你使用的是 Agility SDK 的预览版（Preview version），记得在 Windows 里开启‘开发者模式’；否则它是不会被生效使用的。

备注

如果你想在使用 MinGW 编译的 Godot 中使用 PIX，需要进入 PIX 的运行时（runtime）目录，然后使用以下命令来生成导入库（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 库：

  1. 克隆（Clone） godot-accesskit-c-static 仓库，然后进入该目录。

  2. 运行以下命令：

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

编译带有 WinRT 支持的版本

WinRT 提供了对 OneCore TTS（用于调用 Windows 10 及以上系统的语音库）、HDR 色彩信息监测以及表情符号（Emoji）选择器的支持。

如果你使用的是 MinGW 进行构建，那么开启 WinRT 支持需要额外安装一些依赖项。如果你想跳过这一步，可以在 SCons 编译时使用 winrt=no 这个选项。

你可以在 Godot 源码仓库中运行 python misc/scripts/install_winrt.py 来安装所需的依赖项。运行完这个脚本后，照常编译 Godot 即可。

备注

你也可以选择按照以下步骤，自己手动编译 WinRT 头文件：

  1. 克隆 winrt-mingw 代码仓库，并进入该目录。

  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/

如果你要用自己编译的 WinRT 版本来编译 Godot，需要加上 winrt_path={path} 这个参数，用来告诉 SCons 去哪里寻找 WinRT 的头文件：

scons platform=windows winrt_path=<...>

编译时启用 ANGLE 支持

ANGLE 提供了一个从 OpenGL ES 3.x 到 Direct3D 11 的翻译层（转换层）。它可以用来提升兼容性渲染器（Compatibility renderer）的支持效果，尤其是在那些 OpenGL 驱动过时、比较老旧的显卡上，以及 Windows on ARM 设备上。

使用 ANGLE 进行编译需要安装额外的依赖项。如果你想跳过这一步（不使用 ANGLE），可以在使用 SCons 编译时加上 angle=no 这个选项。

你可以在 Godot 源码仓库中运行 python misc/scripts/install_angle.py 来安装所需的依赖项。运行完这个脚本后，照常编译 Godot 即可。

备注

你也可以选择按照以下步骤，自己手动编译 godot-angle-static 库：

  1. 克隆（Clone） godot-angle-static 仓库，然后进入（navigate to）该目录。

  2. 运行以下命令：

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 的构建按钮构建 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 环境变量里是否包含以下这些程序（binaries）：

# 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 这两个文件就位于该 bin 目录中（例如，如果这两个可执行文件位于 /opt/mingw-w64 目录下，那么这里的路径就填 /opt/mingw-w64/bin ）。

为了确保你的操作完全正确，可以在终端（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 架构。另外，如果你是在不同架构的设备上进行编译，在调用 SCons 时，一定要记得指定正确的 arch= 选项哦。

故障排除

由于默认配置不支持POSIX线程, 因此从某些Ubuntu版本进行交叉编译可能会导致 此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 来创建的，需要带上以下编译标志（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

如果你打算替换掉标准的导出模板，请将这些文件复制到以下位置，并将 <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\ 目录中生成的文件, 因此下次构建时, 将自动引用自定义模板.