在 Apple 芯片 Mac 上构建

前置条件

使用 Apple 芯片 Mac，安装 Xcode 与 Homebrew。上游 README 列出 xcodegen、zstd、spirv-cross、glslang、.NET SDK，以及 Python 包 lz4、capstone、fonttools 和按 Python 版本选择的 backports.zstd。按 README 的最新安装步骤准备，再到开发文档核对构建选项。游戏和 prod.keys 必须由你自己合法取得。本站不提供这些文件或应用下载。先检查你所用提交对应的文档，不要把其他版本的安装步骤混在一起。

区分构建目标

--platform mac 是开发宿主；希望从 Finder 打开的 .app 对应 --platform mac-app。这两个目标都不能代替 iPhone IPA 路线。对照问题报告之前，记录项目提交和游戏版本。

操作步骤

1. 阅读目标提交的 README 和开发文档，确认工具链要求。
2. 按该版本文档整理自己的输入文件，不在问题评论中上传密钥或游戏。
3. 需要 Finder 应用时，采用上游说明的 Mac app 构建目标；保留构建输出和第一条实际错误。
4. 替换已有应用之前，先阅读备份指南并另存存档。
5. 打开构建产物，检查游戏身份与版本。编译通过不能证明性能或稳定性。

可复制的构建示例

在已经准备好的 nxnative 检出目录中，上游 Mac app 路线如下：

python3 scripts/build_ipa_from_nsp.py ~/Games/MarioOdyssey -k ~/keys/prod.keys --platform mac-app

将 ~/Games/MarioOdyssey 替换为自己的游戏输入目录，将 ~/keys/prod.keys 替换为自己的密钥文件。运行前按上游说明核对目录结构。本页仅展示命令，网站不会执行。

预期输出为 <NSP folder>/<game name>.app，游戏名称由输入的控制数据确定；也可用 -o 指定另一 .app 输出路径。完成的 Mac 应用不依赖保留构建目录。先检查预期位置是否生成应用，再从 Finder 打开。

检查点与失败处理

编译失败时记录工具链版本、项目提交和第一条有效错误，先与该提交的要求核对，再决定是否调整依赖。若能启动却停在 Preparing pipelines，继续阅读管线排查指南。不要把删除存档作为编译错误的处理步骤。

将产物与任务对应起来

你拿到的产物	对应用途	接下来检查
Finder 中的 .app 应用	在 Apple 芯片 Mac 上运行	打开预期游戏，检查操作与原有进度
开发宿主构建	Mac 开发与诊断	按这次构建实际打印的运行命令继续
IPA 文件	安装到 iPhone/iPad	转到手机签名与安装路线

终端还在报告编译错误时，调整游戏画面设置不能解决构建阶段的问题。生成应用后才出现启动错误，应将启动提示和日志与编译输出分开保存。尚未准备过项目时，返回设备与工具要求，不要猜测缺少哪一种依赖。

记录一次有用的首次运行

记下 Mac 芯片、macOS 版本、nxnative 提交、游戏版本、输出目标和首次到达的画面，检查操作是否响应、预期存档是否出现。奥德赛专题展示了为什么平台报告应始终对应具体证据。准备画面停滞时继续管线排查；尝试另一构建前先备份存档。