MacNativeGames 完整构建指南:Apple 芯片 Mac 如何一次跑通《塞尔达传说:王国之泪》原生运行
MacNativeGames 是一个让《塞尔达传说:王国之泪》在 Apple 芯片 Mac 上原生运行的开源项目:游戏自身的 ARM64 代码直接跑在苹果芯片上,图形层 NVN 重建在 Metal 之上,不是模拟器。你自备游戏文件与密钥,一条命令就能构建出可玩的 Mac App,从环境核对到构建完成,顺利的话一两个小时可跑通。读完本文,你会知道该准备哪些文件、装哪些依赖、构建命令怎么写,以及常见报错怎么对症处理。
⚖️ 合规提示:你必须拥有正版《王国之泪》,并使用从你自己 Switch 导出的
prod.keys与系统文件。仓库内不含任何游戏内容,构建出的 App 仅供个人使用,请勿分享。
快速上手:一条命令构建 TOTK App
先克隆仓库,再运行构建脚本(下面以 XCI 本体为例,这是最短路径):
git clone https://gitcode.com/gh_mirrors/mac/MacNativeGames
cd MacNativeGames
python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys
命令参数逐个解释:
~/Games/totk.xci:第一个位置参数,游戏文件路径。要求是 1.0.0 本体(标题 ID0100F2C0115B6000)、未压缩的 XCI 或 NSP-k ~/keys/prod.keys:你从自己 Switch 导出的密钥文件路径,构建全程不会打印密钥值- 默认输出就在游戏文件旁边的
Tears of the Kingdom.app,无需其他参数
脚本启动时会逐项检查环境(芯片、系统版本、依赖、空间),任何一项不达标都会立即报错停止,所以下面的环境表建议先核对一遍。构建分 4 大步:1/4 代码(提取并改写三个代码模块)→ 2/4 数据(解密 17 GB RomFS)→ 3/4 着色器(翻译启动着色器)→ 4/4 打包(组装、签名、macOS 首次检查),每步日志写入 TOTK_build/logs/。工作目录 TOTK_build 默认建在游戏文件旁,可用 --work 改位置;再跑一次会复用已完成步骤,可以断点续跑。
环境要求:硬件、系统与文件核对表
| 检查项 | 要求 | 不满足的后果 |
|---|---|---|
| 芯片 | Apple silicon(M 系列) | 报错 needs a Mac with Apple silicon,Intel Mac 不支持 |
| 系统 | macOS 26 或更高(macOS 27 兼容) | 图形层依赖 Metal 4,报错 needs macOS 26 or later (Metal 4) |
| 内存 | 建议 16 GB 或更多 | 游戏运行时需要较大的虚拟内存布局 |
| 磁盘 | 工作目录约 25 GB 空闲,另加游戏文件本身 | 报错 needs about 25 GB free for the work folder |
| 游戏文件 | 本体 1.0.0,未压缩 XCI 或 NSP | NSZ/XCZ 报错 the base game must be an uncompressed XCI or NSP;文件损坏或非 1.0.0 报 SHA-256 校验失败 |
| 密钥 | 你自己的 prod.keys | 无法完成解密,必须通过 -k 传入 |
| 更新包(可选) | 1.1.2 / 1.2.1 / 1.4.3 累计更新,NSP 或 NSZ | 版本不支持时报错,见排障表 |
| 字体来源(可选) | NSP 本体需要 --firmware 或 --shared-fonts | 报错 NSP files do not include system shared fonts |
💡 小提示:磁盘空间有一处可以"省下来"——成品 App 与游戏文件放在同一 APFS 卷时,17 GB 级数据文件通过克隆共享、不占额外空间;如果输出到其他卷,需要另留约 17 GB。XCI 本体默认从其系统更新分区提取字体,一般无需额外操作;NSP 则必须补充字体来源,这是新手最高频的卡点之一。
依赖安装:Xcode 命令行工具与 Homebrew 一键命令
必装依赖只需一次性安装,之后每次构建不再联网装环境:
xcode-select --install
brew install opus libvpx python@3.14
必装依赖及用途:
- Xcode 命令行工具:提供
clang、git、make等构建基础,缺失时报the Xcode command line tools are missing - opus:Homebrew 包,负责游戏音频解码
- libvpx:Homebrew 包,负责预渲染影片(VP9)解码
- python@3.14:构建脚本指定使用 3.14(要用标准库读 zstd 流),系统自带的旧版 Python 不满足要求,缺失时报
Python 3.14 not found
构建所需的 Python 库(cryptography、lz4、capstone、nsz)由脚本自动装入工作目录的虚拟环境,你不需要手动处理,清单见 games/totk/requirements.txt。
推荐安装项:
xcodebuild -downloadComponent MetalToolchain
- Metal 工具链(强烈推荐):装上后构建时把启动着色器预先编译进 App 内部(1.4.3 在 M4 上约 6 分钟);没有它只能编进 macOS 的 Metal 缓存,而这份缓存不跟着 App 走——之后挪动 App 或系统清理缓存,首次启动都要重新编译几分钟并可能卡顿
iPhone / iPad 构建属于额外工具链:需要完整 Xcode 26+(含 iOS 与 Metal 工具链)并执行:
brew install xcodegen cmake ninja
首次 iOS 构建需联网下载并编译设备端库,建议预留 45 GB(带更新包 60 GB)临时空间。
场景变体:NSP 字体、更新包与 iOS 打包命令
按"一个场景一条命令"整理如下:
场景 1:NSP 本体 + 固件目录补字体
python3.14 build_app.py ~/Games/totk.nsp -k ~/keys/prod.keys --firmware ~/Games/firmware
--firmware 指向固件 NCA 目录,用来补 NSP 里缺失的系统共享字体。
场景 2:NSP 本体 + 复用上次提取的六个 .bfttf 字体
python3.14 build_app.py ~/Games/totk.nsp -k ~/keys/prod.keys --shared-fonts /path/to/TOTK_build/totk/extracted/firmware/shared-fonts
场景 3:构建 1.1.2 / 1.2.1 / 1.4.3 更新版(无需先装中间版本)
python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys --update ~/Games/1.4.3.nsp
⚠️ 警告:更新包版本是按文件内容哈希识别的,把别的文件改名成 1.4.3.nsp 没有用,必须是真正的 1.4.3 更新包,否则报 unsupported update module hashes; expected 1.1.2, 1.2.1 or 1.4.3。
场景 4:直接把成品构建到 /Applications(不要构建完再拖过去)
python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys -o /Applications
-o 指定最终路径。
场景 5:构建 iOS 未签名 IPA
python3.14 build_app.py ~/Games/totk.xci -k ~/keys/prod.keys --platform ios -o ~/Games/TOTK.ipa
报错速查:高频构建错误的原因与处理
以下报错都来自 build_app.py 的前置检查与哈希校验,看到即停、对症处理,不要盲目重试:
| 报错信息(节选) | 原因 | 处理办法 |
|---|---|---|
needs a Mac with Apple silicon | Intel Mac 不支持 | 换 Apple silicon 设备 |
needs macOS 26 or later (Metal 4) | 系统版本过低 | 升级到 macOS 26 或更高 |
the Xcode command line tools are missing | 命令行工具未装 | xcode-select --install |
Homebrew packages missing: brew install opus libvpx | Homebrew 依赖缺失 | 按提示 brew install 补齐 |
Python 3.14 not found | 没有 Python 3.14 | brew install python@3.14 |
SHA-256 … is not the expected … (is this Tears of the Kingdom 1.0.0, and the dump complete?) | 游戏文件损坏、不完整或不是 1.0.0 本体 | 重新完整导出,确认是本 1.0.0;哈希基线对照 assets 下的 expected 文件 |
the base game must be an uncompressed XCI or NSP | 本体用了 NSZ/XCZ 压缩格式 | 换成未压缩的 XCI/NSP;NSZ 只能作 --update 更新包 |
NSP files do not include system shared fonts | NSP 缺系统共享字体 | 追加 --firmware <固件NCA目录> 或 --shared-fonts <字体目录> |
unsupported update module hashes; expected 1.1.2, 1.2.1 or 1.4.3 | 更新包版本不受支持 | 准备真正的 1.1.2 / 1.2.1 / 1.4.3 更新包,改名无效 |
needs about 25 GB free for the work folder | 工作目录空间不足 | 清理磁盘或换更大的卷,注意与输出保持同卷 |
needs about 40 GB free … (19 GB extra with base data cached) | 更新版构建空间不足 | 清理磁盘;本体数据已缓存时只需约 19 GB |
not the shader translator this repository ships (its SHA-256 differs from totk_xlate.sha256) | 仓库预编译的着色器翻译器 totk_xlate 不完整或被改动 | 重新克隆仓库获取完整文件 |
macOS checks the new app once (a few minutes for the 16 GB bundle) 后很久没输出 | macOS 正在对新 App 做首次扫描 | 正常现象,保持构建跑完 |
📌 误区提醒:不要看到构建慢就 Ctrl+C。中断后重跑虽能复用已完成部分,但最后一步的 macOS 扫描(约 2–3 分钟)被打断重来最浪费时间。
构建成功后:验证方法与常用文件位置
如何确认构建成功:
- 构建收尾时已用
--check模式跑过一次检查,正常从访达双击 App 即可启动;第一次进入游戏会再校验游戏数据(本地测试约 20 秒) - 构建时别开着其他用 Metal 的程序(比如正在玩的游戏):缓存预热会主动跳过并提示,否则白编一场
- 首次进新场景可能卡顿,是新着色器在编译,属预期行为;缓存写入用户目录后再次进入同一场景会明显变流畅。机制与实测见 docs/first-launch-shaders.md
- 构建跑完、App 能正常游玩后,
TOTK_build工作目录与游戏文件同卷时可放心清理中间产物
常用文件与日志位置,排障时直接找:
存档: ~/Library/Application Support/MacNativeGames/TOTK/profile
着色器缓存: ~/Library/Application Support/MacNativeGames/TOTK/shader-cache (删除 = 全部重新翻译)
运行日志: ~/Library/Logs/MacNativeGames/totk.log (上一次为 totk.previous.log)
构建日志: <游戏文件旁>/TOTK_build/logs/
相关文档与源码:
- 构建脚本:build_app.py(文件头注释完整说明四步流程与依赖)
- 各版本哈希基线:expected-v1.0.0.json、expected-v1.2.1.json、expected-v1.4.3.json —— 所有"SHA-256 不匹配"报错都对照这些文件
- 预编译着色器翻译器说明:games/totk/prebuilt/macos-arm64/README.md
- Metal 缓存预热工具:games/totk/tools/warm_metal_cache.m
- 整体工作原理(为何不是模拟器):docs/how-it-works.md
- 社区着色器共享清单:docs/shader-list.md
- 音频排障:docs/audio-troubleshooting.md
- 运行时源码(宿主服务层):games/totk/runtime/
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



