实现将 HMCL 在 macOS 中打包为 App Bundle 疑难杂症与解决方案讨论

[WhatDamon]

为何要实现？

应 #4450 需求，我也注意到 Glavo 的视频下面偶见用户请求 macOS 使用 App Bundle 分发 HMCL

另外，我还注意到要实现以下功能，必须先实现打包为 App Bundle 这一步：

• [Feature] 添加对于MacOS Sonoma添加的游戏模式的支持 #3831
• [Feature] 为macOS 26引入更为合适的图标 #4117
• [Feature] 在macOS上，代替Simple Voice Chat模组申请麦克风权限 #4494

好处与坏处，详见：#4450 (comment)

问题 / 疑难杂症：

1. HMCL 本体该存放在哪？

随着 #4765 的 Close，代表着 ShulkerSakura/HMCL-MacOS/ 所提供的解决方案不可行，尤其是此项目的解决方案对 macOS 本身就是不合法的（它给人的感觉就是 Windows 下把所有配置文件存放在 EXE 可执行文件内），并且此方法除了可能的权限问题，在添加签名后几乎很难避免报应用程序损坏的错误

• 解决方案 1：下载或复制 JAR 到其他目录
  • 问题 1：App Bundle 和 HMCL 本体更新问题
  • 问题 2：配置可能比较混乱
• 解决方案 2：修改运行目录环境变量
  • 问题 1：HMCL 大概率无法更新

2. HMCL 更新（包括 App Bundle 本体）

上面提到的项目解决方案因为权限也可能面临无法更新

解决方案：#4450 (comment)

---

可能还有更多问题需要解决

[Calboot]

HMCL以及PCL等便携式的启动器打包到 bundle 里面没什么好处吧，纯增加下载时的体积。

虽然 app bundle 可以自带 jre，但是启动游戏本来就需要自己安装 Java ，启动器带不带没啥太大的区别吧？

[zkitefly]

hmcl 打包成 .app 在 macOS 上可以申请必要的权限，改善体验

[WhatDamon]

此外还有游戏模式，启用后 macOS 会在游戏全屏后刻意为游戏倾斜硬件资源，这个只能在 App Bundle 的 Info.plist 中启用，和权限申请一样

另外感觉自带 JRE 感觉属实没有必要，应该鼓励用户自行安装 Java，因为打包在 App Bundle 内的 Java 大概无法快速被 HMCL 识别，并且由于权限问题实际使用可能会有不少限制
个人觉得可以针对 macOS 平台单独提供 HMCLauncher，我也在尝试用 Swift 开发一个看看，现有的 HMCL-dev/HMCLauncher 完全是为 Windows 打造的

[dragon-fish]

弄了个自动化打包 dmg，但单纯就是启动方便点，不用手搓命令行了，没有解决 .minecraft 文件夹默认位于可执行文件目录的问题，希望 HMCL 遵循 macOS 的通用方法，默认使用 Application Support 保存文件

https://github.com/dragon-fish/HMCL-macOS

[WhatDamon]

Application Support 问题见 #4765，另外一提 HMCL 已经在此目录存储正版登录 Token 等敏感信息，理论上可以进行充分利用，但让 HMCL-dev 来实现有点悬了

我目前在想怎么正确存放 HMCL 本体来规避权限问题，并且怎么实现 App Bundle 与 HMCL 的同步更新，尤其是 Glavo 之前画的一个大饼需要 HMCLauncher 的介入，App Bundle 本身的更新问题更加显而易见
关于 Glavo 的大饼我做了这个项目：WhatDamon/HMCLauncher-macOS（目前更新见 refactor 分支，此分支因为上面的 Application Support 问题在启动 JAR 上还没写），顺便改善一下 Shell 脚本的一些交互设计问题，并且尽可能完整实现现有的给 HMCLauncher for Windows 的功能，也给未来添加更多功能一定的施展空间

顺便一说，App Bundle 的主程序若为标准的可执行文件可能会遇到一些棘手的包内权限问题，Shell 文件似乎好一点但在特定条件下也无法避免此问题的发生

[AnemoFlower]

并且此方法除了可能的权限问题

或许可以参考 Terracotta 的安装方式，通过 osascript 让用户授权，然后替换 jar 或者整个 App Bundle？

在添加签名后几乎很难避免报应用程序损坏的错误

可以为每个版本都提供一个签过名的 App Bundle，在更新时直接替换 App Bundle 本体，但这样需要调整更新服务器的逻辑

[WhatDamon]

Terracotta 是使用 pkg 进行打包的，这似乎的确可以被认定为一个解决方案

[AnemoFlower]

关于游戏模式，仅修改启动器的 App Category 可能并不够，它只对启动器本身生效，无法传递到 Minecraft 上。详见 PrismLauncher/PrismLauncher#1644 (comment)
我做了一些研究，开发了 GameStub 这个项目。它具备 App Bundle 的结构和身份，App Category 设置为 Games，并通过 execv 使 Minecraft 进程继承其 Game App 身份，从而激活游戏模式。
目前只在 macOS 26.2 上进行了测试，更多版本还需要进一步验证。

[AnemoFlower]

将 HMCL 打包为 App Bundle 不仅仅是为了游戏模式和麦克风权限申请，这个 Discussion 的目标也不只是“支持游戏模式”。

可以直接用贵项目给HMCL本体打上Info.plist吗

GameStub 并没有“把 Java 程序包装成 App Bundle（打上 Info.plist）/ 把 HMCL 直接变成完整 .app”的能力。它更像是一个用来激活游戏模式的辅助程序。

因此如果目标是规范分发、签名/公证与更新流程，还是需要围绕 App Bundle 方案继续推进。

[673123]

但如果目标只是申请权限，修改图标，也可以先不打成Bundle，Bundle会有太多的限制，严重降低可自定义能力
使用这个方法可以几乎立刻解决#4494

[WhatDamon]

此方案看起来能解决游戏模式的困扰，按照这个思路，代替启动器完成申请权限这一点目前可以通过它做到吗 🤔

[AnemoFlower]

应该可以，添加 NSMicrophoneUsageDescription 属性后，Simple Voice Chat 可以正常申请麦克风权限

[AnemoFlower]

应该可以，添加 NSMicrophoneUsageDescription 属性后，Simple Voice Chat 可以正常申请麦克风权限

启用 Hardened Runtime 后需要开启 com.apple.security.device.audio-input Entitlement 才能申请

[673123]

发现一个重要问题，就是macOS中被一些软件(比如Safari)下载的app会被打上quarantine标签，然后运行时就有可能受到App Translocation，也就是给你拷贝到神秘位置再运行，而且会加上很多限制，比如说这个神秘位置是只读的

只有通过访达将App不和其他文件一起，不随父文件夹一起移动离开最初被解压出的位置才会解除Translocation。或者直接去掉quarantine标签也行

HMCL如果以App Bundle形式分发，也会受到Translocation的影响

[burningtnt]

这个屎 Terracotta | 陶瓦联机已经吃过一次了.jpg

[WhatDamon]

确实棘手，使用 dmg 或 pkg 来包装 App Bundle 作为疑似能够解决此问题，另外在 App Bundle 下，似乎有 quarantine macOS 会以 App 已损坏来阻止用户运行
另外要彻底绕过也不是没有办法，考虑到在 App Bundle 内写游戏文件本身不合适，本身容易导致权限问题，故启动 HMCL 的 Launcher 可能还需要改变 HMCL 的运行目录，这可能能够缓解此问题

[673123]

好像是Quarantine并且验证签名失败的才会说已损坏，验证成功会直接修改quarantine做标记，下次就不会检查了。
pkg就算了吧，可移植性快成负的了

[WhatDamon]

注意到 #5987 的合并，未来可以在 App Bundle 启动 Launcher 时强制给 HMCL 传入相应的环境变量到更加合适的 Application Support 作为配置存储路径（还需要进行调查，因为 Application Support 中已经有了一部分 HMCL 的重要的配置文件），这或许意味着 App Bundle 打包目前的核心问题已经到了更新本体上，公证问题带来的 Gatekeeper 拦截可以在打包为 DMG 的时候附带文档引导玩家放行