#6719·HMCL

[Feature] 支持在 macOS 上直接安装汉化补丁 ZIP

Author: ct-yxCreated Aug 21, 2026Updated Sep 18, 2026

概述 | Summary

希望 HMCL 支持从 ZIP 文件直接安装“汉化补丁/覆盖文件包”到指定的 Minecraft 实例。此类 ZIP 通常使用游戏目录的相对路径(例如 config/kubejs/mods/resourcepacks/vaultpatcher/),并不是一个完整的整合包,不能方便地通过现有的整合包导入流程安装。

On macOS, users should be able to select an instance and a localization overlay ZIP in HMCL and apply it safely without relying on Finder copy/paste or an external script.

原因 | Reason

提出这个功能的直接原因不是单纯找不到实例目录,而是 macOS Finder 对这类补丁的复制、粘贴、目录合并和同名文件覆盖处理不适合实际使用。汉化补丁往往包含大量与现有实例同名的目录和文件,Finder 粘贴后的合并/覆盖结果不够明确,也难以确认是否完整应用,容易导致部分汉化没有生效。

目前用户只能手动尝试 Finder 操作,或运行额外的 .command 脚本。后者虽然可以解决问题,但不是 HMCL 内置能力,普通用户也很难发现和验证脚本来源。

以 All the Mods 10 的一个汉化补丁为例,ZIP 中包含数百个需要覆盖或新增的 config/mods/ 等文件。脚本实际处理了 316 个游戏文件,其中写入 268 个、内容一致跳过 48 个;这说明补丁本质上是“针对已有实例的文件覆盖包”,而不是完整整合包。

详情 | Description

可以在实例菜单或实例文件管理页面增加“导入汉化补丁 / 覆盖文件 ZIP”操作:

  1. 让用户选择目标实例和 ZIP 文件。
  2. 按 ZIP 内的游戏目录相对路径安全地合并文件,而不是依赖 Finder 的粘贴行为。
  3. 预览将要新增、覆盖、跳过的文件,并在覆盖前明确确认。
  4. 仅接受安全的相对路径,拒绝绝对路径和包含 .. 的路径,避免 ZIP 路径穿越。
  5. 安装时保留补丁中未包含的现有文件,并在完成后显示写入、跳过和未处理文件数量。
  6. 如果实现成本允许,可同时支持 Windows、Linux;macOS 是最迫切的使用场景。

该功能不要求 HMCL 识别每个汉化包的具体来源,只需要提供一个安全、可复用的“将 ZIP 内容合并到实例目录”的入口即可。

当前用于验证需求的 macOS .command 脚本(已包含文件校验、原子写入、路径安全检查和处理结果统计)如下:

https://gist.github.com/ct-yx/3bbb2bc4430a2b63fbe813dd1e2f80fa