在 Mac 上原生玩《王国之泪》：MacNativeGames 构建与使用教程

想在 Mac 上玩《王国之泪》，现在可以试试 MacNativeGames。它会处理你提供的游戏文件，将游戏的 ARM64 代码适配到 Apple 芯片上运行，再通过 Metal 完成图形渲染，最后打包成一个可以从访达打开的 Mac App。准备工作主要集中在第一次构建，之后启动游戏就方便多了。

这篇教程面向平时会用 Mac、但不一定熟悉编译工具的玩家。从安装依赖开始，一步步完成本体或更新版的构建，再处理操作、画面和存档。本文只讲 Mac 版。

1. 开始之前，先确认这些条件

机器与空间

项目	要求
Mac	Apple 芯片机型，如 M1、M2、M3、M4、M5；本文流程不适用于 Intel Mac
系统	macOS 26 或更高，使用项目的 Metal 4 图形后端
内存	项目建议 16 GB 或更多；8 GB 机型构建时可能大量使用交换空间
存储	本体构建除原始游戏文件外约需 25 GB；全新本体加更新构建约需 40 GB
网络	安装依赖、获取构建所需的固定版本源码时需要联网

上面的空间估算以工作目录和成品 App 位于同一个 APFS 卷为前提。构建器可以通过 APFS 克隆共享大型数据文件；输出到其他卷，或文件系统不支持克隆时，还要为 App 副本额外预留约 17 GB。空间紧张时，先把磁盘整理好再开始。

游戏文件

准备以下文件：

• 自己的《王国之泪》1.0.0 本体，格式为未压缩的 XCI 或 NSP，标题 ID 为 0100F2C0115B6000。
• 自己的 prod.keys。
• 如果要构建更新版，再准备一份独立的累计更新包，支持 1.1.2、1.2.1、1.4.3，格式为 NSP 或 NSZ。
• 使用 NSP 本体时，还需准备系统共享字体，具体见后文。

本体 NSZ/XCZ、DLC、合并包和个性化票据不在本文所用版本的支持范围内。 更新包可以是 NSZ，不代表本体也可以直接使用 NSZ。构建 1.4.3 时，给出 1.0.0 本体和 1.4.3 的独立累计更新即可，不需要逐个安装中间版本。

2. 安装构建工具

打开 macOS 的“终端”，先安装 Xcode 命令行工具：

xcode-select --install

如果系统提示已经安装，直接继续；如果出现安装窗口，等安装结束再执行后面的命令。

接着安装 Homebrew。按照官网的步骤操作，并完成安装器最后给出的 shell 配置。Apple 芯片 Mac 的默认安装位置是 /opt/homebrew，具体说明见 Homebrew 安装文档。

确认终端能找到 Homebrew，再安装依赖：

brew --version
brew install opus libvpx [email protected]
python3.14 --version

最后一条应显示 Python 3.14.x。后面的命令统一使用 python3.14，避免误用系统自带或其他版本的 Python。

这一版的 Mac 构建流程不要求安装 .NET、CMake 或 iOS 工具链。脚本会继续准备自身需要的环境，完成后的 App 运行时也不需要 Python。

可选：安装 Metal 工具链

如果已经安装完整 Xcode，可以按照 Apple 的附加组件说明安装 Metal 工具链：

xcodebuild -downloadComponent MetalToolchain

项目会利用它将启动着色器预编译进 App。只有命令行工具、没有完整 Xcode 时，可以先跳过这一项：构建仍能进行，只是着色器预编译会使用本机、对应 App 路径的 Metal 缓存。后面移动 App 时，两种方式的差别就会体现出来。

3. 下载源码，整理文件

下面把源码放在 ~/Projects。如果你已经在其他位置下载过，可以直接进入自己的项目目录。

mkdir -p "$HOME/Projects"
cd "$HOME/Projects"
git clone https://github.com/ly05010419/MacNativeGames.git
cd MacNativeGames
git checkout 30a1b93d0776150fbaffd7c20f9a5ca0841c21c9

最后一条将源码切到本文使用的提交。Git 可能提示 detached HEAD，这是查看固定提交时的正常状态，不影响构建。

为了方便看懂命令，后文约定文件像这样摆放，文件名只是示例，请替换成你的实际路径：

~/Games/TOTK/
  base.xci            本体；使用 NSP 时为 base.nsp
  update-1.4.3.nsp     可选的独立更新包
  firmware/           NSP 路线需要，内部是解包后的 .nca 文件

~/keys/
  prod.keys

再创建用户自己的应用目录，把成品直接构建到这里：

mkdir -p "$HOME/Applications"

~/Applications 在你的用户目录下，与系统的 /Applications 是两个位置。本文使用前者，通常不需要管理员权限。提前确定输出位置，也能减少日后移动 App 引起的着色器缓存重建。

4. 选择一条构建命令

以下命令都在刚才的 MacNativeGames 源码目录中运行。按自己的文件情况选一条即可，不需要依次执行。

XCI 本体：先构建 1.0.0

python3.14 build_app.py "$HOME/Games/TOTK/base.xci" \
  -k "$HOME/keys/prod.keys" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

这会构建 1.0.0。通常 XCI 中的系统更新分区能提供共享字体；如果你的 XCI 缺少该分区，也要像下一节那样添加 --firmware 或 --shared-fonts。

NSP 本体：额外提供字体

NSP 本体不带系统共享字体，因此要额外传入已经解包的固件目录：

python3.14 build_app.py "$HOME/Games/TOTK/base.nsp" \
  -k "$HOME/keys/prod.keys" \
  --firmware "$HOME/Games/TOTK/firmware" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

这里的 firmware 应当是包含 .nca 文件的目录，也可以是已安装固件的 registered 目录。不要把固件 ZIP 压缩包直接传给它。

如果以前成功提取过字体，可以把 --firmware 换成：

--shared-fonts "$HOME/Games/TOTK/TOTK_build/totk/extracted/firmware/shared-fonts"

上面是用于替换的参数片段，不是单独执行的命令。它指向的目录需要包含 0-standard.bfttf 至 5-nintendo-extension.bfttf 六个字体。构建器会校验文件，也会复用工作目录内已经有效的字体，不必手动改成系统上的普通字体。

本体加更新：以 1.4.3 为例

XCI 本体加独立更新包：

python3.14 build_app.py "$HOME/Games/TOTK/base.xci" \
  -k "$HOME/keys/prod.keys" \
  --update "$HOME/Games/TOTK/update-1.4.3.nsp" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

如果本体是 NSP，完整命令为：

python3.14 build_app.py "$HOME/Games/TOTK/base.nsp" \
  -k "$HOME/keys/prod.keys" \
  --firmware "$HOME/Games/TOTK/firmware" \
  --update "$HOME/Games/TOTK/update-1.4.3.nsp" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

更新包为 NSZ 时，将 --update 后的路径换成对应 .nsz 文件即可；构建器会处理解压和校验。要构建 1.1.2 或 1.2.1，则换成相应版本的累计更新包。省略 --update 就是构建 1.0.0，不会自动选择更新。

几个参数可以这样记：

参数	作用
build_app.py 后的文件路径	1.0.0 本体
-k	密钥文件
--update	可选的独立累计更新包
--firmware / --shared-fonts	二选一提供字体来源
-o	成品 App 的完整路径，需要以 .app 结尾
--work	可选，自定义中间文件目录

如果不传 -o，成品默认放在本体文件旁边。按本文摆放文件时，默认工作目录是 ~/Games/TOTK/TOTK_build，其中保存提取结果和构建日志。中途遇到可修复的问题，处理后重新运行原命令即可复用已经完成的步骤，先别急着删除整个目录。

构建期间需要等多久

脚本会提取并校验游戏数据、改写程序模块、准备着色器，最后完成打包和签名。终端继续输出进度时，先让它跑完。首次构建受机器内存、磁盘和网络影响很大，着色器编译尤其可能耗时。

项目记录中，8 GB 的 M1 MacBook Air 仅 GPU 着色器编译这一步就可能花约 25 分钟。这只能帮助判断“为什么还没结束”，不能用作你的整次构建耗时预估。

构建完成时，脚本会以 --check 模式检查启动器。这表示可执行文件检查等步骤完成，还需要实际打开游戏，确认画面、声音和操作。

5. 第一次启动，先让它准备好

打开访达，按 Command + Shift + G，输入 ~/Applications，双击 Tears of the Kingdom.app。也可以从终端启动：

open "$HOME/Applications/Tears of the Kingdom.app"

首次启动会校验游戏数据并准备着色器。项目在本地观察到数据校验约需 20 秒，实际等待时间取决于机器和缓存状态。看到进度提示时，先等它完成。

到达标题画面后，其余着色器仍可能在后台预热，第一次进入世界时还可能继续等待。构建器已经从你的游戏数据和公共着色器清单生成首启所需内容，通常不需要另找一份别人分享的缓存。

进入没有走过的场景，仍可能遇到新的着色器变体并短暂卡顿。首次编译与持续低帧率是两种情况：如果同一处第二次经过明显改善，缓存已经发挥作用；如果一直很慢，就要继续看画面设置、内存和具体场景。

App 可以移动吗

可以，但最好在构建前就确定位置：

• 装有 Metal 工具链： 预编译内容随 App 打包，移动后仍能利用这部分内容。
• 没有 Metal 工具链： 本机 Metal 缓存与 App 的位置有关，挪动后可能重新编译。系统清理缓存后也可能发生类似情况。

这也是本文直接用 -o 构建到最终目录的原因。跨卷复制还可能多占一份游戏数据空间，并让 macOS 再次检查 App。

6. 手柄与键盘操作

手柄：先留意确认键的位置

macOS 能识别的兼容手柄，例如 DualSense 和 Xbox 手柄，会映射为 Switch Pro 手柄。默认布局按正面按键的位置对应：

手柄上的位置	Switch 按键	Xbox	PlayStation
右侧	A：确认、互动	B	圆圈
下方	B：取消、冲刺	A	叉
上方	X：跳跃	Y	三角
左侧	Y：攻击	X	方块

因此，拿 Xbox 手柄看到游戏提示“按 A”时，默认要按右侧的 B。体感和震动能否工作，还取决于手柄本身及 macOS 是否提供相应能力。

需要自定义手柄映射时，配置文件在：

~/Library/Application Support/MacNativeGames/TOTK/controls.txt

例如，给 DualSense 的触摸板点击分配地图键：

touchpad = minus

未写出的按键继续使用默认值。修改后重启游戏；如果启动器提示某一行配置有误，按提示检查该行。删除这份配置文件可以恢复默认映射。

键盘：本文固定版本的布局

下面是本文提交版本的默认键盘映射，按键按美式键盘物理位置识别。使用其他版本时，以对应 README 和游戏内快捷键提示为准。

Mac 按键	操作
W、A、S、D	移动，左摇杆
方向键	转动视角，右摇杆
J	A：确认、互动
K 或空格	B：取消、冲刺
I	X：跳跃
U	Y：攻击
Q / E	L / R
Option / Shift	ZL / ZR
F、T、H、G	十字键左、上、右、下
Z / C	按下左摇杆 / 右摇杆
Return	菜单（+）
Tab 或 Esc	地图（−）

7. 画面设置，一次调整一项

先用默认画面进入游戏，确认基础操作正常，再试下面的数字键。这样更容易判断是哪一项设置带来了变化。

按键	作用
1	切换完整信息面板、仅 FPS、全部隐藏
2	切换补帧模式：关闭、30+30、半刷新率、无限制
3	切换 MetalFX 2K、原生 2K、关闭
4	切换 16:9、适配窗口或显示器、21:9；限 1.2.1 / 1.4.3
5	开关 MetalFX 时间性抗锯齿；限 1.4.3

这里有两点容易误会：

• 补帧显示的帧数包含生成帧，不能直接当作游戏逻辑运行帧率。
• “原生 2K”会调整合成画布与 UI，但 3D 场景仍有单独的渲染缩放，不能据此认为所有内部渲染目标都固定为 1440p。

游戏默认跟随 Mac 的语言。如果想临时指定游戏为简体中文，先完全退出游戏，再运行：

open --env TOTK_LANG=zh-Hans "$HOME/Applications/Tears of the Kingdom.app"

这是本次启动的环境变量。已经运行的 App 不会因为再次执行 open 就重新读取这些启动参数。

8. 存档在哪里，更新前怎么备份

成品 App、构建工作目录和个人存档是三处不同的东西：

内容	位置
本文的成品 App	~/Applications/Tears of the Kingdom.app
本文的默认工作目录	~/Games/TOTK/TOTK_build
存档 profile	~/Library/Application Support/MacNativeGames/TOTK/profile
着色器缓存	~/Library/Application Support/MacNativeGames/TOTK/shader-cache
本次运行日志	~/Library/Logs/MacNativeGames/totk.log
上次运行日志	~/Library/Logs/MacNativeGames/totk.previous.log

在访达里按 Command + Shift + G 就能进入这些目录。

更换游戏版本前，先退出游戏，再把整个 profile 文件夹复制到别处备份。启动更新版时，项目还会在 profile 旁创建对应的升级前备份，例如 profile-before-1.4.3；备份失败则停止启动。不要假设新版保存过的进度能被旧版读取，回退时应保留升级前的那份备份。

更新项目代码时，获取你要使用的新版源码，再用原始本体、相同的更新包和输出路径重新构建。先退出正在运行的游戏，并保留原先的 --firmware、--shared-fonts、--work 等必要参数。重新构建到相同路径会替换原 App；存档在上面的用户目录里独立保存。

9. 常见问题

提示找不到 brew 或 python3.14

先检查 Homebrew 安装器要求的 shell 配置是否完成，重新打开终端，再执行第二节的版本检查。即使机器上有 python3，也不代表它就是 Python 3.14。使用 Apple 芯片版本的 Homebrew，避免把另一套 Intel 环境的依赖混进来。

提示缺少 shared fonts

先看本体是不是 NSP。NSP 要传 --firmware 或 --shared-fonts；缺少系统更新分区的 XCI 也需要。确认传入的是解包后的目录，字体目录则应包含六个 .bfttf 文件。

提示版本或哈希不匹配

核对本体是否为 1.0.0，更新包是否为受支持的独立累计更新，文件是否完整，以及密钥是否与自己的内容相符。构建器的校验用于发现不受支持或损坏的输入，不要通过修改预期哈希跳过错误。

双击后迟迟没有游戏窗口

首次启动、移动 App 或跨卷复制后，可能正在进行系统检查或数据校验。先观察进度与日志；如果已经弹出明确错误，就按错误处理。构建阶段的 --check 成功，只说明启动检查完成，不能替代真实游玩验证。

一直卡顿，或者内存压力很大

先关闭其他占用大量内存的程序，查看“活动监视器”的内存压力与交换空间。用 3 键关闭额外的 2K 模式作对照，等后台预热完成，再测试同一场景。不要一边首次编译一边判断整台机器的最终性能，也不必把“删除全部缓存”当作常规优化：缓存删掉后需要重新准备。

有音效，但对白或背景音乐不正常

先确认 macOS 当前音频输出设备和音量，再检查日志中的 CoreAudio 或解码错误。项目已有针对流式音频路径的修复，可参考音频排障文档。仍在使用早期 App 时，用包含修复的源码和原始游戏文件重新构建；着色器编译造成的瞬间停顿也可能打断声音，需要分开判断。

想安装 MOD

先完成一次无 MOD 的构建和启动。之后按项目的 MOD 文档操作：代码补丁通过构建时的 --mod 合入，RomFS 数据文件另有安装和清单要求。不要把其他环境里的 MOD 文件夹直接扔进 App 包。

参考资料

• MacNativeGames：本文对应版本的 README
• 构建脚本与参数定义
• 首次启动与着色器准备说明
• Homebrew 安装文档
• Apple：下载与安装 Xcode 附加组件