实现将 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 打造的

[SinetianLiu]

启动游戏本来就需要自己安装 Java ，启动器带不带没啥太大的区别吧？

当然有。这就好比，一个是自助餐、一个是点单。让小白去研究Java版本对应的Minecraft简直就是灾难……当年KOOK大约80%左右的崩溃求助换个Java就解决了。（扯远了）我想说的是，启动器自带一个可以解决“打不开jar文件“这种智障问题。

[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的影响

[SinetianLiu]

我说句真心话，macOS确确实实比Windows更适合电脑小白。因为它不仅更加简洁、还迁移了iPhone、iPad的操作逻辑（比较典型的案例是App Store），也没有那么多UAC、垃圾软件干扰。所以有那种“连windows和macos都分不清的纯sb“并不是没可能。
我比较担心会有人弄不明白终端的操作。比如说，怎么弄到HMCL的路径？（当然大家都知道直接拖进终端窗口就可以了，但是你可以保证他们弄明白吗？毕竟这东西少空格、少引号都报废。）sudo的密码是什么？（你哪怕告诉他们是登录密码，要是压根没密码、不知道密码、家长不让设怎么办？）
再者，以后要是搞App Bundle分发，又如何移除quarantine标签？如果签名不被认可，又怎么去系统设置手动打开？
总而言之，就是问题多的不行。

最多在文档里写明玩modded java minecraft就是需要技术水平，智障禁入。

这竟然是目前最理想的解决方案……

[SinetianLiu]

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

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

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

我翻了一下，这个用dmg分发就可以解决。可参考下面这段对话。

那 /Applications 到底有什么意义？

它主要解决的是另一个东西：App Translocation（应用转移/随机化运行位置）。

假设你直接从 DMG 里：

/Volumes/Firefox/Firefox.app

运行。

Gatekeeper 可能不会让它直接以这个真实路径运行，而是把它放到一个随机的、只读的位置运行，例如：

/private/var/folders/.../AppTranslocation/.../Firefox.app

这是为了防止恶意 App 利用自己旁边的文件、插件等内容进行攻击。Apple 的开发者文档明确描述了这一机制。

而你把：

Firefox.app

拖进：

/Applications/

然后再启动，macOS 就知道：

“用户已经明确把这个 App 安装到正常位置了。”

因此通常不会再进行 App Translocation，而是从：

/Applications/Firefox.app

正常启动。

[xycabcd]

总之是需要要求用户在访达里把app拖一下。
当然苹果官方并不建议尝试绕开translocation，而是希望通过bundle分发的应用能做到不受translocation影响

[Yuang114514]

总而言之，就是问题多的不行。

申请一个苹果的开发者账号就完全可以减少很多问题
不过我不清楚glavo有没有这个财力
好像这玩意一年就要99美元

[Yuang114514]

当然苹果官方并不建议尝试绕开translocation

苹果官方还不建议安装未签名的应用呢

[WhatDamon]

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

[673123]

发现一个问题，如果App Bundle里面的可执行文件是个脚本，脚本会被用Rosetta转译执行。不确定为什么

[SinetianLiu]

废了，Rosetta到28就没了。

[Yuang114514]

参考这条评论，想必在终端启动HMCL也是可以解决这些问题的。那么为什么不用sh脚本（.command文件）来分发和启动呢？用安装脚本分发的软件也不少。

[Minecraft269]

那么为什么不用sh脚本（ .command 文件）来分发和启动呢？

有sh分发的脚本 依旧是拼接的方式

[Yuang114514]

？我怎么不知道

[Minecraft269]

？我怎么不知道

https://github.com/HMCL-dev/HMCL/releases/download/v3.17.0.353/HMCL-3.17.0.353.sh 这不就是吗

[Yuang114514]

哦......

[SinetianLiu]

不那么好用吧。毕竟终端启动的便捷性和直接双击打开还是不太一样的。

[Yuang114514]

总结一下吧。

目前的解决方案主要有这些：

1. Jar分发+终端启动（当前方案）

直接用jar分发构建文件，在终端执行java -jar HMCL.jar启动。

优点：终端可以申请麦克风权限、更新方便。

缺点：用户不友好、启动不方便、macOS方面的特性无法实现

2.dmg分发

打包成.app包放到dmg里分发。

优点：用户友好、申请权限方便、支持更改图标等功能

缺点：签名弄不好不让运行、公证繁琐、

3.pkg安装包

类似上条。

4.公证签名的dmg.pkg

全套都走apple的那套流程。

优点：官方支持的做法、权限方便

缺点：要付年金

它们要解决这些问题：

• 麦克风权限 [Feature] 在macOS上，代替Simple Voice Chat模组申请麦克风权限 #4494
• 有些模组还可能申请摄像头权限
• 图标 [Feature] 为macOS 26引入更为合适的图标 #4117
• 游戏模式 [Feature] 添加对于MacOS Sonoma添加的游戏模式的支持 #3831
• 顶部栏自定义
• 启动困难/用户不友好
• 打包成appbundle后一大堆权限问题
• 更新

方法/问题	Jar+终端	不签名的dmg/pkg	dmg/pkg+公证
麦克风/摄像头权限	✅	✅	✅
图标	❌	✅	✅
顶部栏	❌	✅	✅
游戏模式	❌	✅	✅
启动方便	❌	✅	✅
权限简明	✅	❌	✅
更新简单	✅	不清楚	不清楚

按什么方法来就看维护者们的意愿了。

[SinetianLiu]

其实有一个办法解决以上所有问题，就是用Swift重写HMCL……
但是这个工作量会极其巨大，所以纯属馊主意，说说得了。

补充几点个人意见：

1. 游戏模式对Minecraft似乎并没有什么决定性影响；感知最明显的帧率也被Mac的屏幕物理限制了（当然，我没用过ProMotion，也没玩过别的游戏，更没玩过什么大型模组，个人意见了）。
2. 启动便利性是一个很大的问题，因为显然在使用jar分发时，没Java=没法启动启动器（套娃了属于是）；使用App Bundle至少可以保证能打开启动器。
3. 菜单栏确实可以改改，但是图标保留意见。主要HMCL不是那种一直呆在dock栏的App，图标观感没那么重要。

[SinetianLiu]

莫名联想到了JetBrains Toolbox和CLion的关系……（扯远了，真扯远了）
那这样还是没有实现那些要求啊？实际上还是用Java启动HMCL。

[Yuang114514]

那这样还是没有实现那些要求啊？实际上还是用Java启动HMCL。

emmm，可以把一切和macos相关的代码都用swift写，就像给HMCL套进一个机甲一样，一切都预备好了

[AnemoFlower]

那这样还是没有实现那些要求啊？实际上还是用Java启动HMCL。

但这样 HMCL 就可以拥有 macOS App Bundle 形式（.app），也就可以实现本 Discussion 提到的功能（被固定在程序坞、申请麦克风权限等）。

[SinetianLiu]

那这样还是没有实现那些要求啊？实际上还是用Java启动HMCL。

emmm，可以把一切和macos相关的代码都用swift写，就像给HMCL套进一个机甲一样，一切都预备好了

过渡方案吧，这个可以让热心用户做fork，HMCL-dev来实现有点悬。

[Yuang114514]

过渡方案吧

那么什么才是终极方案呢