# 测试记录

[← 安装](install.zh-CN.md) · [English](test-records.md)

测过什么、在哪台设备和哪个版本上测的、还有什么没解决。2026-10-26 从安装说明挪到这里；安装说明现在只讲安装。

## 音频修复

已修复 `content://Sound/...` 路径导致的流式音乐和对白读取失败。已在 1.0.0 开场实测对白和配乐，其他版本和场景仍需验证。使用原有游戏输入重新构建 App 即可应用修复，详见[音频排障与验证说明](audio-troubleshooting.md)。

## 本机测试

已在 **MacBook Air M4 和 Mac mini M4** 上测试。本机测试已收集 **8,582 个着色器**，着色器预热后约 **90 帧/秒，菜单中可达 120 帧/秒**。

以上是此前本机观察，不代表所有版本和场景都能稳定达到该帧率。1.4.3 的场景测量及首次编译卡顿另见[测试记录](v1.4.3-port.md)。

着色器会在游玩过程中自动收集、编译并缓存。再次进入已经去过的场景时，可以复用已有缓存，帧数和流畅度通常会明显改善。**8,582 只是本机测试目前收集到的数量，不是游戏的着色器总数，也不是收集上限**；随着探索更多场景，缓存还会继续增加。

**首次启动的着色器预热：** 构建时从你提供的所选版本游戏数据准备着色器并装进 App：游戏数据里的每个着色器按默认绑定状态各准备一个，再加上[公共着色器清单](shader-list.md)里列出的全部变体。即使用户缓存为空，第一次打开也会导入这批着色器。等这些着色器和兼容的管线清单全部预热完、管线写进管线存档后才出标题画面（启动画面显示进度）：装好或公共清单变大后的第一次要等一会儿（王国之泪 1.4.3 在 Apple 芯片的 Mac 上约 60–80 秒：10-26 起管线用多个线程建，以前约 4 分钟；旷野之息 1.6.0 改动前约 50 秒），之后约 12 秒，进游戏时清单里的着色器和管线都已就绪。`TOTK_WARM_BEFORE_TITLE=0` 恢复旧顺序：第一帧前只预热标题画面用到的部分，其余在标题后面继续，第一次进入世界时等它做完（Mac 一直等到做完，iPhone / iPad 最多 15 秒）。不需要先玩一遍或手动复制缓存。当前 1.4.3 准备 15,266 个。打包时还会把它们为本机的 GPU 编一遍。装有 Xcode 的 Metal 工具链时直接编进 App（1.4.3 在 M4 上约 6 分钟），App 挪到哪里都能用；没有工具链时编进 macOS 的 Metal 缓存（几分钟），这时游戏要从打包时的位置运行，Metal 才找得到它们：之后挪动 App（比如挪进 /Applications）、macOS 清掉了缓存（系统盘写满时会清）、或打包时有别的程序正在用 Metal 的缓存（比如开着游戏，打包时会提示），后台预热都要重新编，需要几分钟，做完之前进入新场景可能卡顿。想放在别处，就用 `-o` 直接打包到那里，详见[准备过程与实测记录](first-launch-shaders.md)。还没有玩家报告过的地方仍可能需要新的变体，Mac 会在游玩时现编（第一次会短暂卡顿），并存进本机缓存，以后启动时复用。游戏还会把公共清单里还没有的变体记进 `shader-list-contribution.txt`，每攒够 500 个问一次要不要用 [GitHub Issue](https://github.com/ly05010419/MacNativeGames/issues/new?template=shader-list.yml) 发送这个文件（点“发送”会打开提交页面并显示文件，拖进去即可）。游戏不会自己上传任何东西。会用 git 的话，也可以把本机缓存并入清单再提 pull request，做法见[清单说明](shader-list.md)。清单只有着色器和管线的标识，不含游戏数据、存档或编译后的着色器；每次打包都用玩家自己的游戏文件生成着色器。

## 王国之泪各版本

来源运行时已通过 Mac 基础检查：读档、移动 / 跳跃、菜单 / 地图、2K、保存重读及死亡重试。全地图、长局与 1.0 / 1.1.2 公平性能对比仍待测试；前面的帧率观察不是对 1.1.2 的性能承诺。打包验证范围见[构建记录](how-it-works.md#112-validation)。

1.4.3 另行通过了 M4 Mac 的场景读档、移动 / 跳跃、菜单 / 地图、保存重读、原生 2K 画布切换和 MetalFX 放大 / 补帧。唯一打包 App 已实际验证，另覆盖死亡重试和神庙进出。旧构建三小时及最终版约 30 分钟分开记录；首次编译卡顿、长局内存增长与音频欠载仍待排查，不能视为全游戏或稳定帧率认证。结果、测试方法和后续项见 [1.4.3 适配记录](v1.4.3-port.md)。

1.2.1（10 月 19 日）通过了同样的改写验证（600 个反向对照全部抓到）和加载、RomFS、启动探针。在 M4 Mac 上读过 1.0.0 和 1.1.2 两种格式的存档，并通过移动 / 跳跃、菜单 / 地图 / 快捷菜单、手动存档后新进程读档、摔死重试和 3 键的三种画质；打包后的 App 也从启动器打开测试过。详见 [1.2.1 测试记录](v1.2.1-port.md)；这不代表全流程或长局验收。

**四个地点的 CPU 和 GPU 时间（1.4.3，10 月 28 日，main `e13f030`）。** M4 Mac mini，16 GB，macOS 26.5.2；1920×1080 窗口，场景 1920×1080（游戏自己的动态分辨率有时降到 1720×968、1536×864），默认设置（上限 240 帧，不锁帧，不开 MetalFX）；用各地点的测试存档自动读档后林克站着不动，停 90 秒。数字是游戏自带的每 300 帧计时行的中位数，读档后的前 5 个窗不算。“提交线程 CPU”是回放线程每帧的 CPU，“NVN 提交+出图”是游戏一侧的。

| 地点 | 帧时间 p50 / p95 | GPU p50 / p95 | 提交线程 CPU | NVN 提交+出图 | 每帧绘制 |
|---|---|---|---|---|---|
| 草地（野外） | 11.02 / 11.93 ms（约 91 帧） | 9.57 / 10.38 ms | 4.32 ms | 4.30 ms | 约 3,670 |
| 监视堡垒鸟望台（城镇） | 11.92 / 12.96 ms（约 84 帧） | 9.89 / 10.69 ms | 5.22 ms | 5.19 ms | 约 4,290 |
| 拉希塔奇瓦卡神庙里 | 9.73 / 10.87 ms（约 103 帧） | 8.44 / 9.29 ms | 4.91 ms | 4.78 ms | 约 11,950 |
| 开场醒来的台子（觉醒之间） | 9.48 / 10.51 ms（约 105 帧） | 7.64 / 8.55 ms | 2.05 ms | 1.95 ms | 约 1,030 |

四个地点都是 GPU 先到上限（GPU 占整帧 81–87%，提交线程 2–5 ms 和它并行）。神庙里以前是提交线程拖住（10 月 21 日每帧 7.0 ms、整帧 11.8–11.9 ms），现在是 4.9 ms、整帧 9.7 ms。

**一位玩家的 M3 Pro MacBook Pro（1.4.3，11 月 6–9 日，main 为 `9fe3fdc`）。** MacBook Pro 16 英寸（Mac15,7），Apple M3 Pro，18 核 GPU，18 GB，macOS 26.6.2，内建 120 Hz 屏幕；2K + MetalFX 放大，阴影 2x，SMAA 高，锐化 25%，所有效果开启。这是玩家的观察，没有用仓库的计时工具测量，也没有记下游戏里的地点。

- **运行时更新：** `update_runtime.py` 用了 407 秒，大部分是为这块 GPU 生成管线归档：`applegpu_g15s` 共 27,376 条管线，361 秒，0 失败。
- **更新后的首次启动：** macOS 的 Metal 编译服务占用约七个 CPU 核心约四分钟，读取画面一直等到它结束。之后的启动正常。
- **帧率：** 不锁帧时游戏在 100 帧以上（玩家之后锁在 60 或 72）。
- **长局：** 游戏内存随时间增长：启动四分钟后 4.2 GB，6 小时 47 分后 18 GB（其中 5 GB 被压缩），此时 Mac 开始换页，游戏掉到约 1 帧。退出再打开游戏即恢复（[#1958](https://github.com/ly05010419/MacNativeGames/issues/1958)）。

## 旷野之息

1.6.0 已验证（10 月 20 日，M4 Mac，初始台地的存档）：标题、追加内容一览、读档和存档、台地约 90–120 帧（游戏按真实时间推进，按住按键的重复也按真实时间数）、两个 DLC 内容包挂载并被读取、1 键（提示框）、2 键（MetalFX 补帧：关 → 30+30 → 刷新率一半 → 不限帧，台地上每个游戏帧都插）和 3 键（MetalFX 2K 开 / 关：MetalFX 代替游戏自己把 1600×900 的画面放大进 1080p 画布，窗口大于 1080p 时出图也放大）；台地上 30 分钟约 95 帧、内存平稳（+170 MB）。10 月 23 日起（Mac）：2 键补帧恢复（它认“场景画完”用的着色器键是 10 月 20 日改键之前记的，一帧都认不出来，#177），跟着镜头走的东西（林克）不再套用镜头运动，30+30 下林克不再抖；3 键的 MetalFX 又能代替游戏自己的放大；4 键和 1.9.0 一样切换 21:9（1.6.0 的镜头每帧把比例写回 16:9，所以改的是游戏自己写的那一步）；5 键边缘平滑（#178）。3 键现在和王国之泪 1.4.3 一样循环：关 → MetalFX 2K → 原生 2K → 关（原生 2K 时场景和画布都是 2560x1440；App 启动时就按 2560x1440 建交换链、加大内存堆，`TOTK_OUTPUT_RES=0` 只保留原来的 1080p）。还没有：DLC 的任务本身（只验证了挂载和读取）。这是早期移植，会有毛边。

1.9.0 已验证（10 月 20 日，M1 Pro Mac 的内置 120 Hz 屏幕，两个 DLC 内容包）：标题、读档和自动存档、六个测试地点（从 Shrine of Resurrection 到海拉鲁城出口）站着不动 58.4–77.5 帧，着色器缓存已预热时走动 58.6–81.4 帧、在克洛格森林让林克一直走动的 25 分钟测试、游戏在任何帧率下都按真实时间推进（按住按键的计数也一样）、两个 DLC 内容包（卡卡利科村的路线会触发 DLC 任务 “EX Treasure: Garb of Winds”）、2 键（MetalFX 补帧：关 → 30+30 → 刷新率一半 → 不限帧；在初始台地站着不动时，游戏分别跑 69、30、58 和 61 帧，屏幕每秒显示约 67、60、115 和 115 张画面）和 3 键（MetalFX 代替游戏自己的放大）。从 10 月 21 日起，1.9.0 也有了 1.6.0 在 30 帧以上的修复（菜单和 HUD 速度正常、每帧六次物理步进、过场动画保持 30 帧），底座模式按原生 1080p 渲染，并支持 5 键（MetalFX 时间性抗锯齿：边缘更平滑，1600x900 时台地上约少 9 帧，67.7 降到 58.6）。4 键在 1.9.0 上切换 21:9 宽屏（Mac：镜头两侧看得更多，画面填满更宽的窗口；`TOTK_ASPECT=32:9` 或 `3440x1440` 选别的比例并在启动时就打开；HUD 和菜单在中间 16:9 里保持原来的形状，地图两侧有黑边；跟随世界中物体的标记还没有往外移）。两个版本在 120 Hz 显示器上现在也不限帧，最高 120 帧（在 1.9.0 上测的）；以前游戏的呈现间隔在这种显示器上把帧率压在 60。第一次走进一个地方时，新管线编译会造成卡顿。还没有：原生 2K、iPhone / iPad，以及 main 上林克腿陷进石头路的修复（在初始台地的一个地点读档后出现，旧的自动存档和在那里新存的档都一样）；原因已查明，待合并的拉取请求 #511 修复了腿；main 上的 #239 治好了清澈的 Bottomless Bog 水面，但没有治好腿。详见 [1.9.0 测试记录](botw-v1.9.0-port.md)。

## iPhone 和 iPad

1.4.3 已在 **iPhone 14（iOS 26.6.1）** 和 **A16 芯片的 iPad（iPadOS 26.7.1）** 上实际游玩，两台都是在 Xcode 里用个人开发团队签名安装的。1.0.0、1.1.2 和 1.2.1 没有在 iOS 上测过。旷野之息 1.6.0 已在 iPhone 14 上实际游玩（标题、读档、走动；10 月 23 日）：加 `--platform ios --ios-game-data documents` 构建，和王国之泪一样用 `games/totk/ios/tools/install_device.py` 安装。画面铺满屏幕，内部 960×540，用游戏自己的放大到 1280×720，和王国之泪在手机上一样。1.9.0 也能同样打包（也是 960×540），但还没在手机上玩过。手机上两款游戏都是最高 60 帧（屏幕刷新率）。

- **第一次启动：** App 先校验游戏数据（约 15 秒），再导入随 App 准备的着色器，有进度条。iPhone 14 上约 3 分钟后出现标题画面；之后的启动约 8 秒出标题。
- **画面：** 游戏以掌机模式运行，和 Switch 不接底座时一样：1280×720。
- **着色器：** iPhone 和 iPad 不能在游玩时翻译着色器。App 里没有的着色器变体，对应的绘制会被跳过，所以还没有玩家报告过的地方可能缺少物体。设备会把缺的记进 `shader-list-contribution.txt`（“文件”App › 我的 iPhone › Tears of the Kingdom），玩的时候游戏从不因此打扰你。攒够 100 条时，游戏会在开始前问一次要不要贡献；选“贡献着色器”后，游戏会自己通过 HTTPS 上传（系统“设置”里的“自动贡献着色器”开关可以随时开关）；并入[公共着色器清单](shader-list.md)后，下一次打包时所有人就都有了。有 Mac 的话，也可以用 `games/totk/ios/tools/fill_shaders.py` 马上翻译这些变体并推回设备。
- **内存：** 在 iPhone 14 上游戏占用接近 4 GB，接近手机能给它的上限。在复杂的区域玩几分钟后，手机内存耗尽时 iOS 可能会关掉游戏（iPhone 14 上出现过两次，都在约 8 分钟时）。降低 iOS 上的内存占用是下一步要做的事。

## 自动测试

256 项自动测试覆盖生成的容器 / 更新样本、重定位格式、工作目录隔离、打包、桌面入口迁移、着色器提取（BNSH、agl 的 `.sharcb` 和游戏程序里的着色器）、公共着色器清单和玩家的贡献文件、首次导入的缓存保留、Metal 工具链查找、模组代码补丁合并（用合成 NSO 样本测 IPS / IPS32 / pchtxt，保留地址表直接从 C 源码读出，补丁文件按模块名或 build id 认定）、模组清单自动排除 App 自身覆盖的文件及 27 个原生 RomFS 路径用例。GitHub Actions 已配置为运行源码测试，并在未定义行为检查（UBSan）下运行原生路径解析器，不需要游戏数据或密钥；另使用本地 XCI 构造、附带生成通用票据的 NSP 测试副本完成完整 Mac 打包。尚未验证独立的零售本体 NSP，也未测试从该类输入构建后的实际游玩。