[Feature] 支持在 macOS 上直接安装汉化补丁 ZIP
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 10.1k
- Forks
- 934
- Avg merge
- 1d 5h
- Merged PRs (30d)
- 82
Description
概述 | 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”操作:
- 让用户选择目标实例和 ZIP 文件。
- 按 ZIP 内的游戏目录相对路径安全地合并文件,而不是依赖 Finder 的粘贴行为。
- 预览将要新增、覆盖、跳过的文件,并在覆盖前明确确认。
- 仅接受安全的相对路径,拒绝绝对路径和包含
..的路径,避免 ZIP 路径穿越。 - 安装时保留补丁中未包含的现有文件,并在完成后显示写入、跳过和未处理文件数量。
- 如果实现成本允许,可同时支持 Windows、Linux;macOS 是最迫切的使用场景。
该功能不要求 HMCL 识别每个汉化包的具体来源,只需要提供一个安全、可复用的“将 ZIP 内容合并到实例目录”的入口即可。
当前用于验证需求的 macOS .command 脚本(已包含文件校验、原子写入、路径安全检查和处理结果统计)如下:
https://gist.github.com/ct-yx/3bbb2bc4430a2b63fbe813dd1e2f80fa
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the instance menu or instance file-management entry point and the existing integration-pack import flow. Review how the launcher selects an instance and extracts archive contents before defining the ZIP merge and preview flow. Done means safe relative-path validation, explicit new/overwrite/skip confirmation, preserved unrelated files, and result counts after installation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- desktop, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100