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

构建系统介绍

Godot 主要是一个 C++ 项目，并且它 uses the SCons build system. 我们非常喜爱 SCons，因为它让我们的构建系统变得极易维护且易于配置。得益于此，从源代码编译 Godot 可以变得非常简单，只需要运行：

scons

这（条命令）会为你的当前平台、操作系统和架构编译出一个编辑器版本。你可以通过指定 target（目标）、platform（平台）和/或 architecture（架构）来改变编译出来的产物。例如，如果你想编译一个用于运行导出游戏的导出模板，可以运行以下命令：

scons target=template_release

如果你打算对引擎进行调试或开发，那么你可能想要启用 dev_build 选项，这样可以开启那些专门为开发环境准备的调试代码。

scons dev_build=yes

本文接下来的章节会更详细地解释这些选项以及其他通用的配置选项。不过，在你真正开始编译 Godot 之前，需要先安装一些必要的前置依赖（也就是编译所需的软件和库）。请查阅对应的平台文档来了解更多细节：

• 为 Android 平台编译

• 为 iOS 平台编译

• 为 Linux、*BSD 平台编译

• 为 macOS 平台编译

• 为 Web 平台编译

• 为 Windows 平台编译

这些文章非常详细地介绍了如何在特定平台上搭建编译环境，以及如何进行编译。你可以随时在这些文章和本文之间来回对照参考，查阅针对特定平台的配置选项以及通用的配置选项。

使用多线程

编译过程可能需要花费一些时间，具体取决于你电脑系统的性能强弱。默认情况下，Godot 的 SCons 编译配置会占用除一个核心以外的所有 CPU 线程（这是为了在编译期间让系统依然能保持流畅响应）。不过，如果你的系统只有 4 个或更少的 CPU 线程，它默认就会把所有线程都用上。

如果你想调整 SCons 在编译时使用的 CPU 线程数，可以使用 -j<threads> 参数来指定具体要用多少个线程进行编译。

使用 12 个线程的示例：

scons -j12

选择平台

Godot的构建系统将从检测可构建的平台开始. 如果未检测到, 该平台将不会出现在可用平台列表中. 本教程后续部分将介绍每种平台的构建要求.

仅通过调用 scons 即可调用SCons. 如果未指定平台,SCons将基于主机平台自动检测目标平台. 然后它将立即开始为目标平台构建.

要列出可用的目标平台，请使用 scons platform=list：

scons platform=list
scons: Reading SConscript files ...
The following platforms are available:

    android
    ios
    linuxbsd
    macos
    web
    windows

Please run SCons again and select a valid platform: platform=<string>

要针对特定平台构建（例如 linuxbsd），请在运行时使用 platform=（或者简写为 p=）参数：

scons platform=linuxbsd

生成的二进制文件

生成的二进制文件（也就是编译好的程序）会被放在 bin/ 子目录下，通常遵循以下的命名规则：

godot.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]

对于刚才那次编译尝试，（最终的）结果看起来会是这样的：

ls bin
bin/godot.linuxbsd.editor.x86_64

这意味着该二进制文件适用于 Linux 或 *BSD（ 不是 两者通用），未经过优化，包含了完整的编辑器代码，并且是为 64 位系统设计的。

一个具有相同配置的Windows二进制文件将如下所示:

C:\godot> dir bin/
godot.windows.editor.64.exe

你可以把这个二进制文件复制到任何你喜欢的位置，因为它已经包含了项目管理器（Project Manager）、编辑器以及运行游戏所需的全部功能。不过，它缺少将游戏导出到不同平台所需的数据。为此，你需要下载导出模板（你可以直接从 godotengine.org 下载，也可以自己手动编译生成）。

除此之外, 在所有的构建目标平台中有几个标准选项可以进行设置, 下面将对此进行说明.

目标

target 选项决定了是否编译出编辑器，以及是否启用调试相关的标志。而优化等级（ optimize ）和构建产物中是否包含调试符号（ debug_symbols ），则是与 target 相互独立、分开控制的。每种模式的具体含义如下：

• target=editor ：构建一个编辑器程序（会定义 TOOLS_ENABLED 和 DEBUG_ENABLED 宏）

• target=template_debug：构建一个调试版的导出模板（会定义 DEBUG_ENABLED 宏）

• target=template_release：构建一个正式版的导出模板

所有 PC 目标（Linux、Windows、macOS）上都默认启用了编辑器，其他目标默认禁用。禁用编辑器时得到的二进制文件可以运行项目，但不包含编辑器和项目管理器。

可用的 command line arguments 列表会因构建类型的不同而有所差异。

scons platform=<platform> target=editor|template_debug|template_release

开发别名与生产别名

针对开发创建构建（运行调试工具或性能分析工具）时，你的目的通常与生产构建不同（生产构建要求让二进制文件尽可能又快又小）。

Godot 为此提供了两种别名：

• dev_mode=yes 是 verbose=yes warnings=extra werror=yes tests=yes 的别名，启用了“将警告当作错误”的行为（与 Godot 的持续集成设置一致），并且会构建单元测试，这些测试能够在本地运行。

• production=yes 是 use_static_cpp=yes debug_symbols=no lto=auto 的别名。为 Linux 构建时，静态链接 libstdc++ 可以提升二进制文件的可移植性。在 Linux、Web 和在 Windows 上使用 MinGW 编译时，这个别名还会启用链接时优化（Link-Time Optimization，LTO），而在 macOS、iOS 和在 Windows 上使用 MSVC 编译时 LTO 是禁用的。这是因为这些平台上的 LTO 不是非常缓慢就是生成的代码有问题。

这些别名中的选项可以手动覆盖，在命令行中将其指定为不同的值即可。例如使用 scons production=yes debug_symbols=yes 即可创建针对生产优化并且带有调试符号的二进制文件。

开发构建

备注

请勿混淆 dev_build 与 dev_mode，后者是部分开发相关选项的别名（见上文）。

在进行引擎开发时， dev_build 选项可以配合 target 一起使用，以启用专门针对开发环境的代码。 dev_build 会定义 DEV_ENABLED 宏，禁用代码优化（-O0//0d），启用调试符号的生成，并且不会定义 NDEBUG 宏（这样第三方库里的 assert() 断言就能正常生效了）。

scons platform=<platform> dev_build=yes

这个标志会在生成的二进制文件名后面加上 .dev 后缀（代表 development，即开发版）。

参见

SCons 还提供了一些额外的选项来启用 sanitizers （通常译为“消毒器”或“检测器”），这是一些你可以在编译时开启的工具，能帮你更好地调试引擎中的某些特定问题。详情请参见 使用 Sanitizer 。

调试符号

默认情况下，使用的是 debug_symbols=no ，这意味着编译好的二进制文件中 不会包 含任何调试符号。请使用 debug_symbols=yes 来将调试符号包含进编译好的二进制文件中，这样调试器和性能分析器才能正常工作。此外，如果你希望 Godot 的崩溃堆栈跟踪（crash stacktraces）能够显示出具体的源代码文件名和行号，调试符号也是必不可少的。

但缺点是，调试符号文件非常大（体积通常比程序本身还要大得多）。正因如此，官方发布的二进制文件目前并不包含调试符号。这也意味着，如果你想使用调试符号，就需要自己手动编译 Godot 引擎。

当使用 debug_symbols=yes 时，你还可以加上 separate_debug_symbols=yes 参数，这样会把调试信息单独提取出来，放到一个带有 .debug 后缀的文件里。这样你就可以把这两个文件分开分发了。需要注意的是，在 Windows 平台上使用 MSVC 编译器时，无论你是否设置了 separate_debug_symbols，调试信息 永远 都会被写入到一个单独的 .pdb 文件中。

小技巧

使用 strip <path/to/binary> 命令来移除你已经编译好的二进制文件中的调试符号。

优化级别

以下几种编译器优化级别可供选择：

• optimize=speed_trace（目标平台非 Web 时默认）：执行速度更快，但二进制文件更大。优化有时会对调试器的使用产生负面影响（可能会降低堆栈跟踪的准确性）。如果遇到了这种情况，请改用 optimize=debug。

• optimize=speed：与 optimize=speed_trace 相比，执行速度更快，但二进制文件也更大。与 optimize=debug 相比更不利于调试，因为会尽可能使用最激进的优化手段。

• optimize=size（目标平台为 Web 时默认）：二进制文件更小，但执行速度更慢。

• optimize=size_extra ：相比 optimize=size 选项，它更倾向于生成体积更小的二进制文件，但代价是运行速度会进一步变慢。

• optimize=debug：仅启用不会对调试产生影响的优化手段。得到的二进制文件比 optimize=none 快、比 optimize=speed_trace 慢。

• optimize=none：不进行任何优化。构建时间最快、执行速度最慢。

• optimize=custom（仅限高阶用户）：不会向 C/C++ 编译器传递优化参数。你需要通过 cflags、ccflags、cxxflags SCons 选项手动传递参数。

架构

arch 选项的作用是控制用于运行二进制文件的 CPU 或操作系统版本。主要针对桌面平台，其他平台都会忽略该选项。

arch 选项支持的取值有：auto、 x86_32、 x86_64、 arm32、 arm64、 rv64、 ppc32、 ppc64、 wasm32。

scons platform=<platform> arch={auto|x86_32|x86_64|arm32|arm64|rv64|ppc32|ppc64|wasm32}

使用该标志时，最终得到的二进制文件的末尾会加上 arch 的取值。默认值 arch=auto 会检测与宿主平台匹配的架构。

自定义模块

可以编译驻扎在Godot目录树之外的模块, 以及内置模块.

在编译之前, 可以在命令行中传递一个 custom_modules 构建选项. 这个选项代表了一个以逗号分隔的目录路径列表, 其中包含了一系列独立的C++模块, 这些模块可以被看作是C++包, 就像内置的 modules/ 目录一样.

例如, 可以同时提供包含此类模块的相对, 绝对和用户目录路径:

scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules"

备注

如果有任何自定义模块的目录名与内置模块的目录名完全相同, 引擎将只编译自定义模块. 这个逻辑可以用来覆盖内置模块的实现.

参见

自定义 C++ 模块

清理生成的文件

有时，你可能会遇到一个错误，因为生成的文件存在。你可以使用 scons --clean <options> 删除它们，其中 <options> 是你之前用来构建 Godot 的构建选项列表。

或者，你也可以使用 git clean -fixd 来清理所有平台和配置的构建工件。注意，这将删除版本库中所有未跟踪和忽略的文件。如果你有未提交的工作，请不要运行这个命令！

其他构建选项

你还可以使用其他几个构建选项来配置Godot的构建方式(编译器, 调试选项等), 以及要包含/禁用的功能.

检查 scons --help 的输出, 以获取有关你愿意编译的版本的每个选项的详细信息.

重写构建选项

使用文件

默认的 custom.py 文件可以在Godot引擎源的根部创建, 以初始化任何通过命令行传递的SCons构建选项:

custom.py

optimize = "size"
module_mono_enabled = "yes"
use_llvm = "yes"
extra_suffix = "game_title"

你也可以在编译之前禁用一些内置模块，这样可以节省构建引擎所需的时间。更多详细信息请参见 为尺寸优化构建 （优化大小）页面。

参见

你可以使用在线 Godot 构建选项生成器 , 生成一个包含SCons选项的 custom.py 文件. 然后你可以保存这个文件, 并将其放在Godot源目录的根目录下.

另一个自定义文件可以用 profile 命令行选项明确指定, 都会覆盖默认的构建配置:

scons profile=path/to/custom.py

备注

从文件中设置的构建选项可以被命令行选项所覆盖.

也可以有条件地重写这些选项:

custom.py

import version

# Override options specific for Godot 3.x and 4.x versions.
if version.major == 3:
    pass
elif version.major == 4:
    pass

使用SCONSFLAGS

SCONSFLAGS 是一个环境变量,SCons用来自动设置选项, 而无需通过命令行提供.

例如你可能会想要让后续的构建都使用前面提到的 -j 选项来强制使用特定数量的 CPU 线程：

Linux/macOSWindows (cmd)Windows (PowerShell)

export SCONSFLAGS="-j4"

SCU（单编译单元）构建

普通构建的瓶颈通常在于每个编译翻译单元都包含了大量的头文件。为了加速开发（并非针对生产构建），Godot 提供了“单编译单元”构建（也叫“统一构建”或“巨型构建”）。

在能够被该选项加速的文件夹中，每个翻译单元都会编译多个 .cpp 文件，因此头文件会在多个文件之间共享，从而大幅降低编译时长。

要进行 SCU 构建，请使用 Scons 选项 scu_build=yes。

备注

如果你在使用 SCU（单编译单元）构建模式来开发 PR，请务必在提交 PR 之前先进行一次常规构建。这是因为 SCU 构建天生会包含同一翻译单元中前面 .cpp 文件的头文件，因此它无法检测出你在常规构建中真正需要的所有 #include 依赖。虽然 CI（持续集成）系统最终会捕获到这些错误，但在你自己的本地机器上通过常规构建提前发现它们，通常会快得多。

导出模板

官方的导出模板可以从 Godot 的官方网站 下载到. 此外, 你可能想要自己构建它们(可能想要构建更新的版本, 要使用自定义模块, 不信任我们编译的包是否安全).

如果下载官方导出模板程序包并解压缩, 你会注意到大多数文件都是针对每个平台的优化二进制文件或程序包:

android_debug.apk
android_release.apk
android_source.zip
ios.zip
linux_debug.arm32
linux_debug.arm64
linux_debug.x86_32
linux_debug.x86_64
linux_release.arm32
linux_release.arm64
linux_release.x86_32
linux_release.x86_64
macos.zip
version.txt
web_debug.zip
web_dlink_debug.zip
web_dlink_nothreads_debug.zip
web_dlink_nothreads_release.zip
web_dlink_release.zip
web_nothreads_debug.zip
web_nothreads_release.zip
web_release.zip
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

要自己创建它们, 请按照该教程中针对每个平台的详细说明的部分进行操作. 每个平台都说明了如何创建自己的模板.

version.txt 文件里应该包含对应的 Godot 版本标识符。这个文件的作用是将导出模板安装到特定版本的目录中，以避免发生冲突。例如，如果你正在为 Godot 4.4.1 构建导出模板，那么 version.txt 的第一行应该包含 4.4.1.stable （并且不要有其他任何内容）。这个版本标识符是基于 Godot Git 仓库中<https://github.com/godotengine/godot/blob/master/version.py>`__文件里的 major （主版本）、 minor （次版本）、 patch （修订号，如果有的话）以及 status （状态）这几行信息生成的。

如果你需要为多个平台进行开发，macOS 绝对是跨平台编译最方便的主机平台，因为它可以为所有目标平台进行交叉编译。Linux 和 Windows 紧随其后，但 Linux 的优势在于配置起来更加简单。