Mac 原生移植为何要重编着色器?破解 macOS Metal 缓存“路径长度”之谜

原创2026-10-20 21:22:241,923 阅读
文章标签:逆向工程桌面应用3D渲染音频处理

Mac 原生移植为何要重编着色器?破解 macOS Metal 缓存“路径长度”之谜

MacNativeGames 是一个把 Switch 上的《塞尔达传说 王国之泪》原生移植到 Apple 芯片 Mac(并可构建 iPhone / iPad App)的开源项目。它不依赖模拟器:游戏自己的 ARM64 代码直接在苹果芯片上运行,而原本面向 Switch GPU 的 NVN 图形指令,要在 Mac 上重建于 Metal。本文讲清楚两个问题:为什么从移动端到 Mac 之后,着色器必须重新编译;以及一个连 macOS 官方都没写明的细节——Metal 的缓存命中,竟然取决于程序所在目录的路径长度。🔍

一、为什么“移动 App”到 Mac 后着色器要重编?

先记住一个事实:着色器是为特定 GPU 方言写的,换平台就要换翻译。

  • Switch 显卡(Tegra X1)使用 NVN 图形 API,游戏的数千个着色器都以 NVN 格式存在游戏数据里(BNSH 文件、agl 引擎的 .sharcb 包,甚至嵌在游戏程序 main 模块里)。
  • Mac / iPhone / iPad 上则只有 Metal。于是项目在打包时执行一条翻译链:NVN → SPIR-V(由 totk_xlate 完成)→ MSL(Metal Shading Language,由 SPIRV-Cross 完成)。
  • MSL 只是“源码”,最终还要由 macOS 的 Metal 编译器针对你本机 GPU 编成二进制库。这一步无法在别的机器上提前代劳——编译产物只对同一台机器、同一种 GPU 有效。
平台 能否边玩边编译着色器 结果
Mac ✅ 可以 首次遇到新着色器时短暂卡顿,之后复用缓存
iPhone / iPad ❌ 不可以 App 里没带的变体对应绘制被跳过,画面可能“缺东西”(docs/first-launch-shaders.md)

所以“重编着色器”不是可选项,而是原生移植的物理必然:平台换了,着色器语言换了,GPU 方言也换了。

💡 真正折磨人的不是“要不要编”,而是“编了能不能记住”。这就引出了下文的主角——macOS 的 Metal 缓存。

二、macOS Metal 缓存的“路径长度”之谜

缓存到底存在哪、按什么找

Metal 把编译好的着色器库放进系统缓存:有 bundle ID 的 App 各占一份($(getconf DARWIN_USER_CACHE_DIR)<bundle id>/com.apple.metal);而没有 bundle 的独立程序共用一份(…/C/com.apple.metal)。本项目里,游戏程序是启动器用 execv 替换上来的无 bundle 程序,用的正是这份共用存储。

关键来了。项目团队用 20 个新着色器源码反复交叉验证(在 A 处编译、从 B 处查询)后发现:查这份缓存时,除了着色器源码和编译选项,还要求“程序所在目录的路径长度一样长”——只看长度,不看路径本身(结论详见 docs/first-launch-shaders.md 的“Metal 的缓存”一节,运行时注释见 nvn_mtl.m):

场景(与编译处相比) 缓存命中?
原位置重新打包(路径不变) ✅ 20/20 命中
目录改名、长度相同(X→Y) ✅ 命中
换卷、换目录层级,但长度相同 ✅ 命中
改文件名、改代码签名标识符、改工作目录 ✅ 命中
目录名多一个字符 ❌ 0–2/20
换到长度不同的别处(同卷或别的卷) ❌ 不命中

也就是说:把 App 挪进 /Applications(游戏所在目录路径从 102 个字符变成 68 个),下一次启动缓存直接变冷;而在原地重新打包,缓存安然无恙。看起来像是 macOS 计算缓存键时只取了路径长度(疑似 bug,未来的 macOS 也可能改变行为)。

同一个游戏程序拷到另一个目录(路径长度不同)运行,实测第一帧等了 451 秒——纯粹因为“换了地方”。

冷启动有多疼?

缓存冷的时候,8 千多个着色器库要全部现编(M4 数据,来自 docs/first-launch-shaders.md):

场景 单线程 8 线程
整批预热(约 9,268 个库) 约 14.3 分钟 约 3.1 分钟
缓存热时重启 12.2 秒 1.6 秒(第一帧前仅等 47 ms)

这份共享缓存还有两个“坑”

  1. 淘汰很凶,且不看“最久没用”。 共用存储写满(约 1.08 GB)就开始淘汰:另一个无 bundle 程序一次新编 3,000 个库,1 分钟前刚编的 500 个只剩 6%。系统盘写满时,macOS 还会整份清掉缓存(实测清掉后第一帧等 679 秒)。
  2. 同时只能有一个程序往里写。 若 A 程序先连着这份缓存,B 程序在它运行期间新编的库,A 一退出就几乎全没了。打包脚本因此会用 lsof 检查有没有别的程序占着缓存,占着就跳过预编。

三、MacNativeGames 的四重解法

认清规则后,项目的策略可以概括为:能随 App 走就不依赖系统缓存;不得不依赖的,就“站到正确的位置”去编译。

1. 构建时就把 8,290 个着色器“装进 App”

prepare_shader_seed.py 扫描你游戏数据里的全部着色器(含 agl 的 .sharcb 包),离线翻译成 MSL 并生成“种子”随 App 分发;首次启动导入到用户缓存(位于 ~/Library/Application Support/MacNativeGames/TOTK/shader-cache)。

更妙的是:若装有 Xcode 的 Metal 工具链,build_app.py 还会用 step_shader_libs 把每个 MSL 预编译成 build/shader-libs/<源码 SHA-256>.metallib 直接放进 App。这些库跟着 App 走,挪到哪里都命中,彻底绕开“路径长度”问题(1.4.3 在 M4 上约 6 分钟)。

2. 没有工具链?把预编工具“放进和游戏一样长的目录”

tools/warm_metal_cache.m 是打包时的小工具:它被临时拷进 App 内游戏程序的目录(Contents/Resources/totk/build/,路径与游戏程序完全等长),用与游戏完全相同的编译选项、8 个线程把种子的全部 MSL 编进系统 Metal 缓存,再用新进程抽查 64 个验证命中,最后把自己删掉。

实测效果(M4,1.4.3):

预编工具放在哪 游戏整轮预热 第一帧前等待
别的目录(路径长度不同) 175–181 秒(一个都没命中) 约 325 ms
游戏程序的目录(等长) 4.4 秒 18 ms

这也解释了为什么“想放在 /Applications 就用 -o 直接打包到那里”——打包位置就是缓存生效位置。

3. 第一帧只等“标题清单”,其余后台并行编

全部 8,290 个排在最前面时,第一帧要等它们全部编完。现在 共享着色器清单 中带 t 标记的 1,445 行(标题画面、主菜单、存档列表用到的着色器)优先:第一帧只等这一小撮,其余在标题画面后面按 512 行一块、多线程后台预热。

旧顺序(种子先) 新顺序(标题清单先)
第一帧 5.8 秒 2.0 秒
第一帧前等待 3.8 秒 0.1 秒
进入世界 27 秒 19–22 秒

后台预热线程数由 TOTK_WARM_THREADS 控制(Mac 默认核数减 2、最多 8,iOS 固定 1),进世界后自动降到 2 个线程,免得和游戏抢核(实现见 nvn_mtl.m 的 warm 逻辑)。

4. 防御:预编失败不砸场子

  • 种子导入失败(文件损坏、磁盘写满)时,启动器显示“着色器缓存未就绪”后照常进游戏,边玩边翻译,而不是黑屏退出;
  • 打包时发现别的程序占着 Metal 缓存会主动跳过预编并说明是哪个程序(相关打包逻辑有 test_warm_metal.py 等自动测试守着)。

四、实用建议:如何让你的缓存一直保持“热”

  1. 想放 /Applications?用 -o 直接打包过去。 打包完成的位置就是 Metal 缓存的“锚点”,事后移动 = 缓存作废。
  2. 打包时别开着别的大 App 或正在跑游戏。 打包器会用 lsof 检查缓存占用并跳过预编;你也可以手动确认:lsof $(getconf DARWIN_USER_CACHE_DIR)com.apple.metal。
  3. 别把系统盘写满。 macOS 磁盘紧张时会清掉整份 Metal 缓存,下次启动又要现编几分钟。
  4. 日志是判断依据。 首次启动日志出现 [shader-seed]、启动关键管线已就绪、管线预热完成 三行,说明种子导入与预热正常;复测方法见 docs/first-launch-shaders.md。
  5. 新场景卡顿是正常的。 玩家还没报告过的地方仍可能需要新变体,Mac 会边玩边编(第一次短暂卡顿);它同时会记进 shader-list-contribution.txt,并入共享清单后,大家的下一次构建就都不会再卡在那里了(机制见 docs/shader-list.md)。

五、常见问题(FAQ)

Q:为什么刚构建完、第一次启动还要等几分钟? A:大概率缓存是冷的——你挪动过 App、系统清过缓存,或打包时有别的程序占着 Metal 缓存。8 线程后台预热约 3 分钟(M4),期间能玩,只是新场景会卡;之后启动基本秒进。

Q:为什么把 App 拖进 /Applications 就变慢了? A:目录路径长度变了,Metal 共享缓存的键对不上,等于缓存清零。正确姿势是重新构建时加 -o 直接输出到 /Applications。

Q:如何确认自己的缓存是热的? A:冷编译每个着色器库约 50–130 ms,命中只有 0.1–0.5 ms。看启动日志里 管线预热完成 的耗时即可:几毫秒到几秒 = 热,几百秒 = 冷。

Q:iPhone / iPad 上还有这个问题吗? A:手机读的是打包时预编译好的 metallib,不现编,所以没有“路径长度”问题;代价是它不能边玩边补,缺的变体会被跳过并记入贡献文件。

写在最后

“重编着色器”是跨平台原生移植无法绕开的成本,而 MacNativeGames 的价值在于:把成本从“玩家的第一次启动”挪到“打包时”,并且用大量受控实验摸清了 macOS Metal 缓存的真实脾气——按 bundle 分、按签名分都不对,真正(也许只是碰巧)关键的是那条路径的长度。等 macOS 哪天修正了这个疑似 bug,这套预编策略也只是多一层保险罢了。

想亲手验证?克隆仓库 MacNativeGames,按 README 准备游戏文件与 prod.keys,运行 build_app.py 构建你自己的 App 吧。

📄 延伸阅读:docs/first-launch-shaders.md(完整实测数据)· docs/how-it-works.md(移植原理)· docs/performance-followups.md(性能复测方法)

登录后查看全文
MacNativeGames