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

为 macOS 平台编译

备注

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

需求

在 macOS 下编译时，需要以下条件：

Python 3.9+。
SCons 4.4+ 构建系统。
Xcode（或更轻量的 Xcode 命令行工具）。
MoltenVK 所需的`Vulkan SDK <https://sdk.lunarg.com/sdk/download/latest/mac/vulkan-sdk.dmg>`_ （因为 macOS 系统本身并不原生支持 Vulkan）。你也可以直接运行 Godot 源码仓库里的 misc/scripts/install_vulkan_sdk_macos.sh 脚本，来快速安装最新版本的 Vulkan SDK。

备注

如果你已经安装了 Homebrew ，可以使用以下命令轻松安装 SCons：

brew install scons

如果你还没有 Xcode 命令行工具，安装 Homebrew 也会自动进行获取。

同样地，如果你已经安装了 MacPorts，也可以通过以下命令轻松安装 SCons：

sudo port install scons

参见

关于获取 Godot 源码以便进行编译，请参见获取源代码。

有关 Godot 的 SCons 用法的一般概述，请参阅构建系统介绍。

编译

启动终端, 进入引擎源代码的根目录.

如果要为搭载 Intel（x86-64）芯片的 Mac 进行编译，请使用：

scons platform=macos arch=x86_64

如果要为搭载 Apple Silicon（ARM64）芯片的 Mac 进行编译，请使用：

scons platform=macos arch=arm64

小技巧

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

如果一切顺利，编译好的二进制可执行文件就会出现在 bin/ 子文件夹里。这个可执行文件已经包含了完整的引擎，不需要任何额外的依赖就能直接运行。双击执行它，就会弹出 Godot 的项目管理器界面啦。

备注

不建议直接使用独立的编辑器可执行文件，最好始终把它打包成 .app 程序包，以免出现 UI 激活方面的问题。

备注

如果你想为自己的 Godot 构建和官方发布使用单独的编辑器设置，你可以通过在 bin/ 文件夹中创建一个名为 ._sc_ 或 _sc_ 的文件来启用自包含模式。

编译时启用 AccessKit 支持

AccessKit 提供了对屏幕阅读器的支持。

如果要编译并集成 AccessKit 功能，需要先安装额外的依赖项。如果你不想处理这些依赖（想跳过这一步），可以在使用 SCons 编译时加上 accesskit=no 这个选项。

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

备注

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

克隆（Clone） godot-accesskit-c-static 仓库，然后进入该目录。
运行以下命令：

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

编译 AccessKit 静态库时，应该使用和你编译 Godot 时完全相同的编译器。

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

scons platform=macos accesskit_sdk_path=<...>

编译时启用 ANGLE 支持

ANGLE 提供了一个从 OpenGL ES 3.x 到 Metal 的转换层，可以用来改善某些搭载了过时 OpenGL 驱动的老旧 GPU 在兼容性渲染器下的支持效果。

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

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

备注

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

克隆（Clone） godot-angle-static 仓库，然后进入（navigate to）该目录。
运行以下命令：

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

你也可以通过加上 arch={architecture} 来指定编译的架构。

ANGLE 静态库应该使用和你编译 Godot 时相同的编译器来构建。

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

scons platform=macos angle_libs=<...>

自动创建 `.app` 捆绑包

如果想要像官方发行版那样自动生成一个 .app 程序包，可以在构建编辑器的 最后一条 SCons 命令中，加入 generate_bundle=yes 这个选项：

scons platform=macos arch=x86_64
scons platform=macos arch=arm64 generate_bundle=yes

手动创建 `.app` 捆绑包

如果想要在一个单独的 "Universal 2" （通用 2）二进制文件中同时支持这两种架构，请先运行上面那两条编译命令，然后使用 lipo 工具将它们打包合并在一起：

lipo -create bin/godot.macos.editor.x86_64 bin/godot.macos.editor.arm64 -output bin/godot.macos.editor.universal

要创建 .app 程序包，你需要使用位于 misc/dist/macos_tools.app 的模板文件。通常来说，当你构建了一个带有 dev_build=yes 参数的优化版编辑器二进制文件时，就可以用到它：

cp -r misc/dist/macos_tools.app ./bin/Godot.app
mkdir -p bin/Godot.app/Contents/MacOS
cp bin/godot.macos.editor.universal bin/Godot.app/Contents/MacOS/Godot
chmod +x bin/Godot.app/Contents/MacOS/Godot
codesign --force --timestamp --options=runtime --entitlements misc/dist/macos/editor.entitlements -s - bin/Godot.app

备注

如果你正在构建 master 分支的代码，你还需要加入对 MoltenVK（Vulkan 可移植性库）的支持。默认情况下，它会从你安装的 macOS 版 Vulkan SDK 中静态链接。当然，你也可以通过传入 use_volk=yes 参数，并将动态库包含在你的 .app 程序包中，来选择动态链接它：

mkdir -p <Godot bundle name>.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/lib/libMoltenVK.dylib <Godot bundle name>.app/Contents/Frameworks/libMoltenVK.dylib

运行无头/服务器构建

如果要在 headless 下运行，以便在自动化流程中利用编辑器的功能来导出项目，请使用常规构建版本。

scons platform=macos target=editor

然后使用 --headless 这个命令行参数：

./bin/godot.macos.editor.x86_64 --headless

要编译一个可以与 remote debugging tools 配合使用的调试版 服务器 构建，请使用：

scons platform=macos target=template_debug

如果要编译一个经过优化、专门用来运行专用游戏服务器的发布版 服务器 构建，请使用：

scons platform=macos target=template_release production=yes

构建导出模板

要构建 macOS 的导出模板，你必须使用不带编辑器（editor）的目标来进行编译：也就是 target=template_release （发布版模板）和 target=template_debug （调试版模板）。

官方模板是 Universal 2 二进制文件，同时支持 ARM64 和 Intel x86_64 两种架构。

支持 ARM64（苹果 Apple Silicon 芯片）和 Intel x86_64：

scons platform=macos target=template_debug arch=arm64
scons platform=macos target=template_release arch=arm64
scons platform=macos target=template_debug arch=x86_64
scons platform=macos target=template_release arch=x86_64 generate_bundle=yes

仅支持 ARM64（也就是苹果的 Apple Silicon 芯片，比如 M1/M2/M3 等）（这样做的好处是文件体积更小，但缺点是对旧款硬件的兼容性较差）：
scons platform=macos target=template_debug arch=arm64 scons platform=macos target=template_release arch=arm64 generate_bundle=yes

如果你想制作一个像官方发行版那样的 .app 程序包，就需要使用位于 misc/dist/macos_template.app 的模板文件。这个过程可以通过在构建导出模板的 最后一条 SCons 命令中加入 generate_bundle=yes 参数来实现自动化（这样就能把所有编译好的二进制文件都包含进去）。执行后，它会在 bin/ 目录下生成一个 godot_macos.zip 文件，并且还会自动调用 lipo 工具，把事先编译好的 ARM64 和 x86_64 两个独立的二进制文件合并，打包成一个 通用 2（Universal 2） 架构的二进制程序。

备注

你还需要加入对 MoltenVK（Vulkan 可移植性库）的支持。默认情况下，它会从你安装的 macOS 版 Vulkan SDK 中静态链接。当然，你也可以通过传入 use_volk=yes 参数，并将动态库包含在你的 .app 程序包中，来选择动态链接它：

mkdir -p macos_template.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/libs/libMoltenVK.dylib macos_template.app/Contents/Frameworks/libMoltenVK.dylib

在大多数情况下，更推荐使用静态链接，因为它能让软件的分发变得更加简单。而动态链接的主要优势在于，它允许你在不需要重新编译导出模板的情况下，直接更新 MoltenVK。

如果你是手动创建的 .app 文件，那么你可以直接压缩 macos_template.app 这个文件夹，来还原（生成）出和官方 Godot 发行版里一模一样的 macos.zip 导出模板：

zip -r9 macos.zip macos_template.app

想要使用你的自定义导出模板，你可以在导出预设（export presets）的高级选项（advanced options）中，选中 godot_macos.zip 这个文件。

或者，如果你希望所有的预设都使用你的自定义导出模板，你可以把 godot_macos.zip 这个文件重命名为 macos.zip，然后把它移动到导出模板的默认存放位置：

::: ~/Library/Application Support/Godot/export_templates/<GODOT_VERSION>/macos.zip

从 Linux 交叉编译 macOS

在Linux环境下为macOS进行编译是可行的(也许也可以在Windows中使用Windows Subsystem for Linux). 为此, 你需要安装 OSXCross , 以便能够使用macOS作为目标. 首先, 按照说明来安装它:

在你的电脑任意位置克隆 OSXCross repository （或者下载 ZIP 压缩包并解压到任意位置），例如：

git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross"

按照说明打包SDK:https://github.com/tpoechtrager/osxcross#packaging-the-sdk
按照说明安装OSXCross:https://github.com/tpoechtrager/osxcross#installation

完成上述步骤后，你需要将 OSXCROSS_ROOT 这个环境变量定义为你的 OSXCross 安装路径（也就是你当初克隆仓库或解压 ZIP 压缩包所在的同一个目录），例如：

export OSXCROSS_ROOT="$HOME/osxcross"

现在，你就可以像平常一样用 SCons 来进行编译啦：

scons platform=macos

如果你安装的 OSXCross SDK 版本和 SCons 构建系统默认期望的版本不一致，你可以通过 osxcross_sdk 这个参数来手动指定一个自定义的版本：

scons platform=macos osxcross_sdk=darwin15

故障排除

致命错误：找不到 'cstdint' 文件

如果你在编译刚开始不久就遇到了这种形式的报错，很可能是因为你的 macOS 系统或 Xcode 刚刚更新过，导致 Xcode 命令行工具的安装需要修复一下：

./core/typedefs.h:45:10: fatal error: 'cstdint' file not found
45 | #include <cstdint>
   |          ^~~~~~~~~

运行这两条命令来重新安装 Xcode 命令行工具（如果需要的话，请输入你的管理员密码）：

sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install

如果还是不行，可以尝试从 Mac App Store 更新 Xcode，然后再试一次。