引言

最近给我的启动器添加了MuiltiMC整合包安装的支持，所以在这里分享一下我的开发过程，顺便就当作复习了。

启动器新版本转向了Rust，所以实例代码也会用Rust。

在实现过程中，我参考了HMCL对MMC整合包导入的实现

MMC整合包介绍

Muilt-MC(MMC) 整合包依旧是1个zip格式的压缩包，但是打包方式与常见的 CurseForge / Modrinth 整合包完全不一样，因为 CF / MR 整合包都是基于自家的资源平台来打包的，都有自己的资源api，可以做到几乎所有文件都基于自家平台的api+mojang的资源api来实现，几乎除了config外的所有文件都可以在线下载，但MMC整合包不一样，他是MuiltiMC启动器的整合包导出格式，没有像MC/MR一样的资源平台，基本除了Minecraft资源文件外的内容都要打包到文件中，或者整合包开发者自己提供资源文件链接。

这最大的缺陷就是这种什么都打包的整合包格式会导致打包出的整合包文件格外的大，比如同样的RCraft整合包，CF打包只有约200MB，而MMC却有超过500MB。

但MMC整合包的优点也是很明显的，其自由度和功能性远超 CF 和 MR 整合包。MMC 整合包除了可以支持 Forge NeoForge Fabric Quilt 这类常见加载器外，还可以支持 CleanRoom Babric 等小众加载器，只要你的游戏可以启动，MMC整合包就可以打包，所以像 GTNH 这样的深度魔改包采用的都是 MMC格式 的整合包打包。

实现思路

MMC整合包 的安装核心思路就一句话：把 MultiMC 的组件补丁链（OneSix scheme）转换成一个标准 Mojang 官方版本 JSON，之后启动走普通安装/启动管线。

0.整合包结构

打开一个MMC整合包，其内部的大概结构如下(以GTNH为例子)：

1
2
3
4
5
6
7
8
9
10
11
GT New Horizons 2.8.4
├─ patches
│  ├─ org.lwjgl3.json
│  └─ ···
├─ libraries
│  └─ lwjgl3ify-2.1.16-forgePatches.jar
├─ .minecraft
│  └─ ···
├─ mmc-pack.json
├─ instance.cfg
└─ gtnh_icon.png

其中，mmc-pack.json 和 instance.cfg 就是整合包的配置文件，我们便是从中读取启动器信息的。

这两个文件的作用：

文件 内容
instance.cfg（INI） 实例名、iconKey、JavaPath（仅 OverrideJavaLocation=true 时）、MaxMemAlloc（仅 OverrideMemory=true 时）
mmc-pack.json components[]，每个是 {uid, version, dependencyOnly}

1.获取整合包信息

先读 instance.cfg。它就是个再朴素不过的 INI，逐行 key=value 切一刀就完事：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
fn parse_instance_cfg(content: &str) -> HashMap<String, String> {
    let mut map = HashMap::new();
    for line in content.lines() {
        let line = line.trim();
        // 跳过空行和 #/; 开头的注释
        if line.is_empty() || line.starts_with('#') || line.starts_with(';') {
            continue;
        }
        // 按第一个 = 切开，左边是 key，右边是 value
        if let Some((k, v)) = line.split_once('=') {
            map.insert(k.trim().to_string(), v.trim().to_string());
        }
    }
    map
}

然后是重头戏 mmc-pack.json。GTNH 2.8.4 的它长这样（去掉 cachedName 之类的缓存字段）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "components": [
        {
            "uid": "org.lwjgl3",
            "version": "3.3.3",
            "dependencyOnly": true
        },
        {
            "uid": "net.minecraft",                        
            "version": "1.7.10",      
            "important": true },
        {
            "uid": "me.eigenraven.lwjgl3ify.forgepatches", 
            "version": "2.1.16" 
        },
        { 
            "uid": "net.minecraftforge",
            "version": "10.13.4.1614" 
        },
        { 
            "uid": "me.eigenraven.lwjgl3ify.launchargs", 
            "version": "2.1.16" 
        }
    ],
    "formatVersion": 1
}

components 就是这个实例的「零件清单」：每个组件是一层对游戏的修改，一层层叠出最终的游戏。

我们要读取他拿到 uid ，然后去 patches 文件夹找{uid}.json，没有的从 maven 服务器下载。

解析它的代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
/// 单个组件
struct MmcpComponent {
    uid: String,           // 组件唯一标识，比如 "net.minecraft"
    version: String,       // 期望的组件版本
    dependency_only: bool, // true = 只是别的组件的依赖，不是用户主动装的东西
}

fn parse_mmc_components(content: &str) -> Result<Vec<MmcpComponent>, String> {
    let v: Value = serde_json::from_str(content)?;
    let arr = v.get("components").and_then(Value::as_array)
        .ok_or("mmc-pack.json 缺少 components")?;
    let mut comps = Vec::new();
    for c in arr {
        let uid = c.get("uid").and_then(Value::as_str).unwrap_or("");
        if uid.is_empty() { continue; }
        // uid 来自整合包内容，是不可信输入：之后要拿它拼本地路径
        // patches/{uid}.json 和下载 URL，所以只放行 [A-Za-z0-9._-]，
        // 其余替换成 _，防止路径穿越 / URL 注入
        let uid = sanitize_component_id(uid);
        // 清洗后还不允许出现 .. 和路径分隔符
        if uid.is_empty() || uid.contains("..")
            || uid.contains('/') || uid.contains('\\') {
            continue;
        }
        comps.push(MmcpComponent {
            uid,
            version: c.get("version").and_then(Value::as_str).unwrap_or("").into(),
            dependency_only: c.get("dependencyOnly")
                .and_then(Value::as_bool).unwrap_or(false),
        });
    }
    Ok(comps)
}

拿到组件清单后，从中提取启动器关心的元信息：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 游戏版本：找 uid == "net.minecraft" 的组件，它的 version 就是游戏版本
// （GTNH 这里 = "1.7.10"）。找不到直接报错，没有游戏版本一切免谈
let game_version = components.iter()
    .find(|c| c.uid == "net.minecraft")
    .ok_or("mmc-pack.json 缺少 net.minecraft 组件")?
    .version.clone();

// 主加载器：优先挑 uid 能映射到已知加载器的组件。
// GTNH 的组件里混着 forgepatches / launchargs 这类辅助组件，
// 无脑取"第一个非 minecraft 组件"就会被 lwjgl3ify 骗到，
// 所以先过一遍已知加载器映射表（forge/neoforge/fabric/quilt/optifine...）
let loader = components.iter()
    .find(|c| !c.dependency_only && c.uid != "net.minecraft"
             && !loader_candidates(&c.uid, &game_version).is_empty())
    // 实在匹配不上（自定义加载器），才回退取第一个非 minecraft 组件
    .or_else(|| components.iter()
        .find(|c| !c.dependency_only && c.uid != "net.minecraft"));

注意:
components 的顺序就是后面组件补丁的修补顺序，不能随意调换，安装时必须按序读取（为什么顺序重要，第 4 节讲合并时揭晓）。

2.读取组件补丁

现在有个问题：第 1 节拿到的 components 里只有 uid + version，根本没提主类、库列表、启动参数这些信息。那游戏的完整定义藏在哪？

答案是每个组件自己的一份 JSON 补丁（patch）文件：patches/{uid}.json。MMC 的版本定义就是拆成一叠补丁的——net.minecraft 一张、Forge 一张、LWJGL 一张——安装时按顺序一张张叠上去，最终叠出一份完整的版本定义（这套 scheme 叫 OneSix，instance.cfg 里的 InstanceType=OneSix 说的就是它）。

GTNH 2.8.4 的 patches 目录正好 5 个文件，和 components 一一对应：

1
2
3
4
5
6
patches
├─ org.lwjgl3.json                              ← LWJGL 3.3.3 的库表
├─ net.minecraft.json                           ← 修正过的 1.7.10 完整定义
├─ me.eigenraven.lwjgl3ify.forgepatches.json    ← lwjgl3ify 内嵌库 + 一大串 JVM 参数
├─ net.minecraftforge.json                      ← Forge 10.13.4.1614
└─ me.eigenraven.lwjgl3ify.launchargs.json      ← 最终主类

补丁的读取是三级回退，本地优先：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
async fn load_patch(root: &Path, uid: &str, version: &str, game_version: &str)
    -> Result<Value, String>
{
    // 1.整合包内自带 patches/{uid}.json（GTNH 的 5 个补丁都在这）
    // 2.实例根 {uid}.json（旧版布局的兼容写法）
    for p in [
        root.join("patches").join(format!("{uid}.json")),
        root.join(format!("{uid}.json")),
    ] {
        if p.is_file() {
            let content = std::fs::read_to_string(&p)?;
            return serde_json::from_str(&content);
        }
    }
    // 3.都没有就问 MultiMC 官方 meta 服务器
    //    （原版 MC、LWJGL 这类通用组件的补丁托管在这里）。
    //    version 为空时先按 uid 补默认版本：LWJGL 系列有约定俗成的值，
    //    intermediary 这类 mappings 的默认版本就是游戏版本，
    //    不补的话 URL 都拼不出来
    let ver = default_version(uid, version, game_version);
    let url = format!("https://meta.multimc.org/v1/{uid}/{ver}.json");
    let resp = http.get(&url).send().await?.error_for_status()?;
    // 404 直接失败：包里没有本地补丁、meta 上也没有，这组件没救了
    Ok(resp.json().await?)
}

随手放个最小的真实例子，GTNH 的 launchargs 补丁全文就这么多：

1
2
3
4
5
6
7
8
{
    "formatVersion": 1,
    "name": "LWJGL3ify launch args",
    "uid": "me.eigenraven.lwjgl3ify.launchargs",
    "version": "2.1.16",
    "order": 100,
    "mainClass": "com.gtnewhorizons.retrofuturabootstrap.Main"
}

它只干一件事：把主类改成 RFB（RetroFuturaBootstrap）的引导类。

3.补齐依赖闭包

只按 mmc-pack.json 列出的组件加载补丁是不够的，每个补丁里还有 requires 字段声明自己依赖谁。GTNH 里就有两个例子：

  • net.minecraft.json 声明 requires org.lwjgl3 (suggests 3.3.3)——这份 1.7.10 补丁被改造成了配 LWJGL3 用的；
  • net.minecraftforge.json 声明 requires net.minecraft (equals 1.7.10)。

所以加载完一圈后要再扫一遍所有补丁的 requires：依赖的 uid 不在已加载集合里，就按 suggests/equalsVersion 指定的版本补加载，新补丁又可能带来新依赖，循环直到闭包收齐为止。之后才有资格谈合并。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// 补齐依赖闭包：新补丁可能带来新依赖，只能循环到收敛为止
loop {
    let mut missing: Vec<(String, String)> = Vec::new();
    for patch in patches.values() {
        // 扫每个补丁的 requires: [{uid, suggests/equalsVersion}]
        for r in patch.get("requires").and_then(Value::as_array).unwrap_or(&vec![]) {
            let Some(rid) = r.get("uid").and_then(Value::as_str) else { continue };
            // net.minecraft 是 base（Mojang 官方 JSON）一定有的，跳过；
            // 已经在集合里的也跳过
            if rid == "net.minecraft" || patches.contains_key(rid) { continue; }
            // 取依赖版本：优先 equalsVersion，其次 suggests
            let ver = r.get("equalsVersion").or_else(|| r.get("suggests"))
                .and_then(Value::as_str).unwrap_or("").to_string();
            missing.push((rid.to_string(), ver));
        }
    }
    // 一圈扫下来谁都不缺 → 闭包收齐，收工
    if missing.is_empty() { break; }
    for (rid, ver) in missing {
        // 新加载的补丁下一轮循环还会被扫 requires
        patches.insert(rid, load_patch(root, &rid, &ver, game_version).await?);
    }
}

4.合并出官方版本 JSON

万事俱备，开始拼装。合并的 base 不是空白 JSON，而是先从 Mojang 拉一份官方版本 JSON（版本清单 → 版本 URL → JSON），然后把补丁一个个打上去：

1
2
3
4
5
6
// 1.Mojang 官方版本 JSON 打底：先拉版本清单找到目标版本的 URL，
// 再拉对应的版本 JSON，里面有主 jar 下载地址、资源索引、官方库表
let base = fetch_mojang_version_json(http, &meta.game_version).await?;
let mut merged = base;
// 2.id 换成实例名，之后它就是一个以实例名命名的普通版本
merged["id"] = json!(version_dir_name);

合并语义不是简单的「同 key 覆盖」，每个字段有自己的规则。核心的 patch 应用函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
/// 把一个组件补丁应用到 base 上
fn apply_patch(base: &mut Value, patch: &Value) -> Result<(), String> {
    for (key, val) in patch.as_object()? {
        // MultiMC 用键名前缀表达操作类型：
        //   "-xxx" → 从结果里删除 xxx
        //   "+xxx" → 往结果里追加 xxx（数组语义）
        //    "xxx" → 设置/覆盖 xxx
        let (op, name) = if let Some(rest) = key.strip_prefix('-') {
            ("remove", rest)
        } else if let Some(rest) = key.strip_prefix('+') {
            ("add", rest)
        } else {
            ("set", key.as_str())
        };
        match op {
            "remove" => { base.as_object_mut().unwrap().remove(name); }
            _ => match name {
                // 库表：按 maven 坐标去重拼接（同名整体覆盖，见 merge_libraries）
                "libraries" => merge_libraries(base, val),
                // tweakers / jvmArgs：拼接语义，暂存到临时键。
                // 因为 tweakers 里可能既有 Forge 的 FMLTweaker
                //   又有其他组件的，互相覆盖会丢
                "tweakers"  => append_to_arr(base, "__tweakers", val),
                "jvmArgs"   => append_to_arr(base, "__jvm_args", val),
                // mainJar 仅记录备查：主 jar 下载地址以 base 的
                // downloads.client 为准
                "mainJar"   => { /* 存进 __main_jar */ }
                // compatibleJavaMajors 换算成 javaVersion：
                // 取 {8,11,16,17,21} 交集里最大的作为 majorVersion
                "compatibleJavaMajors" => apply_java_majors(base, val),
                // mainClass / minecraftArguments 等标量：后定义者胜出
                "mainClass" | "minecraftArguments" | "assetIndex" | ··· => {
                    base.as_object_mut().unwrap().insert(name.into(), val.clone());
                }
                // order/requires/conflicts/suggests 是 MultiMC 自己的
                // 元信息，对启动游戏没用，合并时直接忽略
                "order" | "requires" | "conflicts" | "suggests" | ··· => {}
                _ => { /* 未知键保守替换，避免关键字段丢失 */ }
            },
        }
    }
    Ok(())
}

其中 merge_libraries 的「同名整体覆盖」值得单独看：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/// 库表合并：按完整 maven 坐标去重拼接，同名者后定义者整体覆盖
fn merge_libraries(base: &mut Value, val: &Value) {
    let base_arr = base.get_mut("libraries").and_then(Value::as_array_mut).unwrap();
    // 先给 base 库表建索引：maven 坐标 → 所在下标
    let mut seen: HashMap<String, usize> = HashMap::new();
    for (i, lib) in base_arr.iter().enumerate() {
        if let Some(n) = lib.get("name").and_then(Value::as_str) {
            seen.insert(n.to_string(), i);
        }
    }
    for lib in val.as_array().unwrap() {
        let name = lib.get("name").and_then(Value::as_str).unwrap_or("");
        if let Some(&idx) = seen.get(name) {
            // 同名：整条替换（保留原位置），保证后打的补丁赢
            base_arr[idx] = lib.clone();
        } else {
            // 新库：追加到末尾
            seen.insert(name.into(), base_arr.len());
            base_arr.push(lib.clone());
        }
    }
}

应用顺序：dependencyOnly 的组件先打，其余按 mmc-pack.json 的声明顺序依次打——这就是第 1 节说「顺序不能乱换」的另一半原因：

1
2
3
4
5
6
7
8
9
10
// dependency-only 组件（如 LWJGL3）先打，为主组件铺路；
// 主组件再按 components 声明顺序依次叠上去
let mut order: Vec<String> = Vec::new();
let mut deps: Vec<String> = Vec::new();
for c in &meta.components {
    if c.dependency_only { deps.push(c.uid.clone()); }
    else if patches.contains_key(&c.uid) { order.push(c.uid.clone()); }
}
for uid in &deps  { apply_patch(&mut merged, &patches[uid])?; }
for uid in &order { apply_patch(&mut merged, &patches[uid])?; }

这里有个我踩过的最大的坑：net.minecraft 补丁自带 libraries 时，要用它整体替换 base 的库表，而不是合并：

1
2
3
4
5
6
7
8
9
10
// net.minecraft 补丁自带库表 → 整体替换，不进 merge_libraries！
// MultiMC 的 net.minecraft.json 是修正后的完整库表（gson 2.10.1、
// log4j -fixed、剔除 LWJGL2），普通合并会把 Mojang 官方 JSON 里的
// 旧库（gson 2.2.4 / LWJGL 2.9.1）残留下来，新旧库挤在同一个
// classpath 里打架，启动直接 VerifyError(当然如果你的启动器在启动拼接classPath时会去重提取新版应该不影响)
if let Some(libs) = patches.get("net.minecraft")
    .and_then(|p| p.get("libraries").and_then(Value::as_array))
{
    merged["libraries"] = Value::Array(libs.clone());
}

原因：GTNH在 MultiMC包 的 net.minecraft.json 是一份修正过的完整库表——gson 升到了 2.10.1、log4j 换成了修复版 2.0-beta9-fixed（挂在 Prism Launcher 的镜像仓库上）、并且剔除了全部 LWJGL2（改用组件里的 LWJGL3，以兼容Java 17+）。如果只做普通合并，Mojang 官方 JSON 里的旧库（gson 2.2.4、LWJGL 2.9.1）会残留在 classpath 里新旧打架，启动直接 VerifyError (当然如果你的启动器在启动拼接classPath时会去重提取新版应该不影响)。

拿 GTNH 走完整个链路后的合并结果举例（libraries 有几十项就省略了）：

1
2
3
4
5
6
{
    "id": "GTNH 2.8.4",
    "mainClass": "com.gtnewhorizons.retrofuturabootstrap.Main",
    "minecraftArguments": "--username ${auth_player_name} --version ${version_name} ··· --tweakClass cpw.mods.fml.common.launcher.FMLTweaker",
    "javaVersion": { "component": "java-runtime-gamma", "majorVersion": 17 }
}
  • mainClass：原版是 net.minecraft.client.main.Main，被后面的补丁覆盖成了 RFB 引导类；
  • minecraftArguments：还是旧格式的参数串，Forge 补丁的 +tweakers 在末尾追加了 --tweakClass；
  • javaVersion：compatibleJavaMajors [17,21,23,24,25] 换算出 majorVersion = 17。1.7.10 本来是跑在 Java 8 上的，是 lwjgl3ify 这类深度魔改把它推到了 Java 17+——启动器如果不知道这件事，默认选个 Java 8 就直接寄了。

最后还有一步收尾：把库里只有 maven 坐标、没有下载信息的条目物化成 Mojang 格式的 downloads.artifact：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/// 物化 maven-only 库的下载信息（Mojang 格式的 downloads.artifact）
fn materialize_library_downloads(merged: &mut Value) {
    for lib in merged.get_mut("libraries").unwrap().as_array_mut().unwrap() {
        // 有 downloads 的（net.minecraft / lwjgl3 补丁里那些）已经齐了，跳过
        if lib.get("downloads").is_some() { continue; }
        // maven 坐标 → 仓库相对路径：
        // "com.typesafe:config:1.2.1"
        //   → com/typesafe/config/1.2.1/config-1.2.1.jar
        let name = lib["name"].as_str().unwrap();
        let maven_path = maven_to_path(name);
        // 特例：MMC-hint: local = 文件在整合包里自带，不需要下载，
        // url 先留空
        let is_local = lib.get("MMC-hint").map(|h| h == "local").unwrap_or(false);
        let url = if is_local {
            String::new()
        } else {
            // 这里处理url
            // 库自带 url（如 Forge 的 maven.minecraftforge.net）就拼上去；
            // 没有就落到 Mojang 官方库仓库
            let repo = lib.get("url").and_then(Value::as_str)
                .unwrap_or("https://libraries.minecraft.net/");
            format!("{repo}{maven_path}")
        };
        lib["downloads"] = json!({ "artifact": {
            "path": maven_path, "url": url, "size": 0, "sha1": ""
        }});
    }
}

5.落盘安装

到这里一份标准的官方版本 JSON 就诞生了。

完整的流程：

flowchart TD
    A["读取 mmc-pack.json + instance.cfg"] --> B["加载组件补丁
patches/ → 实例根 → meta.multimc.org"]
    B --> C["递归补齐 requires 依赖闭包"]
    C --> D["以 Mojang 官方版本 JSON 为 base 依序合并"]
    D --> E["写出 versions/{实例名}/{实例名}.json"]
    E --> F["拷贝内嵌库到共享 libraries/"]
    F --> G["对照合并结果扫描缺失文件
主 jar / 库 / 资源 → 下载"]
    G --> H["拷贝 .minecraft 用户内容
到版本隔离目录"]
    H --> I["收尾：图标 / JVM 参数 / 实例记录"]

剩下的流程和安装一个普通版本几乎没有区别：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// merged = 第 4 节合并好的版本 JSON，jvm_args = 组件收集的 +jvmArgs
// inst_svc / instance_id = 实例服务与本次安装的实例 id（写 jvmArgs 用）
async fn run_multimc_import(root: &Path, meta: &MultiMcMetadata,
    game_dir: &str, name: &str, merged: &str, jvm_args: &[String])
    -> Result<(), String>
{
    // 1.写出版本 JSON：从此它就是一个以实例名命名的普通版本
    let version_dir = Path::new(game_dir).join("versions").join(name);
    std::fs::create_dir_all(&version_dir)?;
    std::fs::write(version_dir.join(format!("{name}.json")), &merged)?;

    // 2.内嵌库先行（必须在下载扫描之前！原因见下文）
    copy_embedded_libraries(root, Path::new(game_dir), &merged)?;

    // 3.对照合并结果扫描缺失文件：主 jar / 库 / 资源索引，
    //    缺什么下什么（复用启动器现有下载管线）
    let miss = get_miss_files_from_json(game_dir, merged).await?;
    download_batch(miss).await?;

    // 4.拷贝 .minecraft 用户内容到版本隔离目录
    copy_instance_content(root, Path::new(game_dir), name)?;

    // 5.+jvmArgs 写进实例设置（版本 JSON 塞不了这个，原因见下文）
    if !jvm_args.is_empty() {
        let mut inst = inst_svc.get_by_id(instance_id)?;
        inst.jvm_args = Some(jvm_args.join(" "));
        inst_svc.update(instance_id, inst)?;
    }
    Ok(())
}

几个值得单独说的点：

内嵌库先行。MMC-hint: local 的库要先于下载步骤处理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/// 拷贝内嵌库：{整合包}/libraries/{文件名} → {GameDir}/libraries/{maven路径}
/// GTNH 的 lwjgl3ify 库 maven 坐标是
///   com.github.GTNewHorizons:lwjgl3ify:2.1.16:forgePatches
/// 对应文件就躺在整合包 libraries/ 下：
///   lwjgl3ify-2.1.16-forgePatches.jar
/// 落到启动器共享库目录：
///   com/github/GTNewHorizons/lwjgl3ify/2.1.16/lwjgl3ify-2.1.16-forgePatches.jar
fn copy_embedded_libraries(src_root: &Path, game_root: &Path, merged: &str) {
    for lib in maven_local_libraries(merged) {
        // 内嵌文件 = maven 路径的末段文件名
        let embedded = src_root.join("libraries").join(&lib.basename);
        if !embedded.is_file() { continue; }
        let dest = game_root.join("libraries").join(&lib.maven_path);
        if !dest.is_file() { std::fs::copy(embedded, dest)?; }
    }
}

顺序很重要——这类库的 url 是空的，如果先跑缺失扫描，扫描器会把空 url 兜底成官方库仓库地址，然后对着一个不存在的地址 404。

用户内容拷贝。整合包 .minecraft/ 下全是用户内容（GTNH 这里是 mods、config、journeymap、resourcepacks 这些），直接拷到实例的版本隔离目录 versions/{实例名}/ (如果不开版本隔离就直接丢游戏文件夹，一般这类整合包安装都要版本隔离)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/// 拷贝 .minecraft/ 的直接子项到版本隔离目录
fn copy_dir_children(src: &Path, dest: &Path, shared_libs: &Path) {
    // 运行时垃圾 / 会被重建的目录跳过，别把上一个启动器
    // 跑出来的日志也搬进新实例
    const SKIP_DIRS: &[&str] = &[
        ".cache", "logs", "downloads", "crash-reports",
        "cache", "versions", "assets",
    ];
    for e in std::fs::read_dir(src)?.flatten() {
        let name = e.file_name().to_string_lossy().into_owned();
        if SKIP_DIRS.contains(&name.as_str()) { continue; }
        if e.path().is_dir() {
            // 特例：.minecraft/libraries 归入启动器共享库目录，不进实例目录
            let target = if name == "libraries" { shared_libs.into() }
                         else { dest.join(&name) };
            copy_tree(&e.path(), &target)?;
        } else {
            std::fs::copy(e.path(), dest.join(&name))?;
        }
    }
}

JVM 参数落实例设置。+jvmArgs 拼出来的那一大串参数（GTNH 的几十个 --add-opens）不塞进版本 JSON——MultiMC 的 +jvmArgs 不是 Mojang 标准字段，塞进旧格式 JSON 反而会因为缺 arguments.game 导致启动报错。写进实例自己的 JVM 参数设置里，启动时统一生效。

总结

回顾一下，MMC 整合包安装的本质是一场「格式翻译」：

  • instance.cfg + mmc-pack.json 提供实例元数据和组件清单；
  • 每个组件按 patches/{uid}.json → 实例根 → meta.multimc.org 三级回退取补丁，再用 requires 递归补齐依赖闭包；
  • 以 Mojang 官方版本 JSON 为 base 依序合并（记住 net.minecraft 的库表是替换不是合并），产出一份标准官方版本 JSON；
  • 之后内嵌库先行、下载缺失文件、拷贝用户内容到版本隔离目录，一切回归普通安装管线。

理解了「补丁链合并」这个核心，剩下的都是工程问题：例如加载器怎么映射、内嵌库怎么处理、恶意 uid 怎么防之类。这些可以看看 HMCL 的实现。

说些什么吧！

waline