Minecraft Launcher 启动失败：Unable to prepare assets for download 的一次排查

环境：Zorin OS 18.1 / Minecraft Launcher / Fabric Loader

问题描述

点击启动 Minecraft Java Edition 时，启动器弹窗报错：

ERROR
Launching the game failed!

Internal error.
Name: REQUEST_FAILED
Error details: Unable to prepare assets for download

表面看像是游戏文件损坏、资源文件缺失、网络无法连接 Mojang，或者 Fabric 安装坏了。实际根因更具体：当前启动项指向的版本描述文件缺失，启动器因此走到了一个已经不可用的旧资源索引地址。

直接结论

这次不是整个 .minecraft 损坏，也不是存档、mods 或资源包损坏。

真正缺失的是：

~/.minecraft/versions/fabric-loader-0.18.5-1.21.11/fabric-loader-0.18.5-1.21.11.json
~/.minecraft/versions/1.21.11/1.21.11.json

当前启动器配置中，选中的 profile 是：

fabric-loader-1.21.11 -> fabric-loader-0.18.5-1.21.11

但 ~/.minecraft/versions/ 里没有这个 Fabric 版本目录。启动器尝试补全版本和资源索引时，请求了旧地址：

https://s3.amazonaws.com/Minecraft.Download/indexes/legacy.json

该地址现在返回：

HTTP/1.1 404 Not Found

于是启动器最终报：

Unable to prepare assets for download

排查过程

第一步：确认磁盘和权限

先排除常见问题：

df -h ~/.minecraft
ls -ld ~/.minecraft ~/.minecraft/assets ~/.minecraft/assets/indexes ~/.minecraft/versions

本次检查结果：

根分区还有约 31GB 空间
.minecraft、assets、versions 都可读写
不符合磁盘满、权限错误、只读文件系统的特征

第二步：看启动器日志

官方启动器日志在：

~/.minecraft/launcher_log.txt

用关键字筛选：

rg -n -C 10 'Unable to prepare assets|REQUEST_FAILED|legacy.json|Minecraft.Download/indexes' ~/.minecraft/launcher_log.txt

关键日志：

NetQueue: Starting net action https://s3.amazonaws.com/Minecraft.Download/indexes/legacy.json
Action finished: https://s3.amazonaws.com/Minecraft.Download/indexes/legacy.json
URL: https://s3.amazonaws.com/Minecraft.Download/indexes/legacy.json
Launcher/launcher (main) Error Unable to download https://s3.amazonaws.com/Minecraft.Download/indexes/legacy.json to <APPDIR>/assets/indexes/legacy.json
response code: 404

这说明启动器不是无法联网，而是下载了一个不存在的资源索引。

同时，launchermeta.mojang.com、piston-meta.mojang.com 等新地址可以正常访问：

curl -I -L https://launchermeta.mojang.com/mc/game/version_manifest_v2.json

因此问题不是简单的网络中断。

第三步：检查启动器 profile

查看启动器配置：

python3 -m json.tool ~/.minecraft/launcher_profiles.json | rg -n 'lastVersionId|fabric-loader|name'

根本原因

官方启动器启动 Fabric 版本时，Fabric 的版本 JSON 通常只描述 loader 本身，并通过 inheritsFrom 继承原版 Minecraft 版本。

本次重新生成的 Fabric JSON 中可以看到：

{
  "id": "fabric-loader-0.18.5-1.21.11",
  "inheritsFrom": "1.21.11",
  "mainClass": "net.fabricmc.loader.impl.launch.knot.KnotClient"
}

也就是说，启动器需要同时拿到两层版本信息：

fabric-loader-0.18.5-1.21.11.json
1.21.11.json

如果 Fabric 版本 JSON 缺失，启动器无法正常解析继承链和资源索引，可能退回到旧逻辑或旧缓存路径，最终请求已经失效的 legacy.json。

这类问题在强制断电后更容易出现。Minecraft Launcher 会频繁写入日志、缓存、版本 JSON、资源索引和 UI 状态。掉电发生在写入过程中时，文件系统结构可能仍然一致，但应用层的小型 JSON 文件可能丢失或不完整。

最小修复方案

不要先删除整个 .minecraft，也不要先清空 assets。优先补齐缺失的版本 JSON。

第一步：补 Fabric 版本 JSON

mkdir -p ~/.minecraft/versions/fabric-loader-0.18.5-1.21.11

curl -fsSL \
  'https://meta.fabricmc.net/v2/versions/loader/1.21.11/0.18.5/profile/json' \
  -o ~/.minecraft/versions/fabric-loader-0.18.5-1.21.11/fabric-loader-0.18.5-1.21.11.json

第二步：补原版 1.21.11 版本 JSON

先从本地版本清单确认 URL：

python3 - <<'PY'
import json
from pathlib import Path

p = Path.home() / ".minecraft/versions/version_manifest_v2.json"
data = json.loads(p.read_text())

for item in data["versions"]:
    if item["id"] == "1.21.11":
        print(item["url"])
        break
PY

本次对应 URL 为：

https://piston-meta.mojang.com/v1/packages/77c6eeceec7ef93945e19cf1fe036605a5bde95b/1.21.11.json

下载：

mkdir -p ~/.minecraft/versions/1.21.11

curl -fsSL \
  'https://piston-meta.mojang.com/v1/packages/77c6eeceec7ef93945e19cf1fe036605a5bde95b/1.21.11.json' \
  -o ~/.minecraft/versions/1.21.11/1.21.11.json

第三步：补资源索引

检查 1.21.11.json 里的资源索引：

python3 - <<'PY'
import json
from pathlib import Path

p = Path.home() / ".minecraft/versions/1.21.11/1.21.11.json"
data = json.loads(p.read_text())
print(data["assetIndex"]["id"])
print(data["assetIndex"]["url"])
PY

本次结果：

29
https://piston-meta.mojang.com/v1/packages/4d558f228dfa2ba7d5b294b588fa00c81b425832/29.json

下载：

curl -fsSL \
  'https://piston-meta.mojang.com/v1/packages/4d558f228dfa2ba7d5b294b588fa00c81b425832/29.json' \
  -o ~/.minecraft/assets/indexes/29.json

验证

检查当前启动项指向的版本是否存在：

python3 - <<'PY'
import json
from pathlib import Path

mc = Path.home() / ".minecraft"
profiles = json.loads((mc / "launcher_profiles.json").read_text())["profiles"]

for profile in profiles.values():
    version = profile.get("lastVersionId")
    if not version:
        continue
    path = mc / "versions" / version / f"{version}.json"
    print(("OK" if path.exists() else "MISSING"), profile.get("name") or "(unnamed)", "->", version)
PY

本次修复后，当前要启动的 profile 应显示：

OK fabric-loader-1.21.11 -> fabric-loader-0.18.5-1.21.11

确认本地版本文件中不再引用旧资源索引：

rg -n 'Minecraft\.Download/indexes/legacy\.json|"assets"\s*:\s*"legacy"' \
  ~/.minecraft/versions ~/.minecraft/assets/indexes ~/.minecraft/launcher_profiles.json

正常情况下没有输出。

如果启动器仍报同样错误，完全退出 Minecraft Launcher 后重新打开。启动器进程可能缓存了旧版本状态。

关于不要直接删除 `.minecraft`

网上常见建议是“删除 .minecraft 重新下载”。这个做法能解决部分问题，但代价过大：

saves/ 是存档
mods/ 是模组
config/ 是模组配置
resourcepacks/ 是资源包
shaderpacks/ 是光影
screenshots/ 是截图
replay_recordings/ 是录像

这次真正需要修的是 versions/ 里的两个 JSON 和 assets/indexes/ 里的一个资源索引。删除整个目录属于过度处理。

更稳妥的顺序是：

查 launcher_log.txt
查 launcher_profiles.json 当前 profile 的 lastVersionId
查 versions/<version>/<version>.json 是否存在
查继承的原版版本 JSON 是否存在
查对应 assets/indexes/<id>.json 是否存在
只补缺失文件

掉电后的经验

这次问题很可能和一次强制掉电有关。Linux 文件系统通常能保证文件系统结构不崩，但不保证应用刚写入的所有用户数据都完整保存。

尤其是启动器这类应用，会频繁写小文件：

版本 JSON
资源索引 JSON
登录状态
UI 状态
缓存数据库
日志

突然断电后，最容易坏的不是大文件，而是这种“小但关键”的元数据文件。

建议备份优先级：

~/.minecraft/saves
~/.minecraft/mods
~/.minecraft/config
~/.minecraft/resourcepacks
~/.minecraft/shaderpacks
~/.minecraft/screenshots
~/.minecraft/replay_recordings

assets/、libraries/、versions/ 大多可以重建，但如果当前启动器状态已经混乱，最好先查日志和版本 JSON，不要直接清空。

总结

现象	真正含义
`REQUEST_FAILED`	启动器内部下载/准备资源失败，不一定是游戏主体损坏
`Unable to prepare assets for download`	资源索引准备失败，重点查 `assets/indexes` 和版本 JSON
`legacy.json` 返回 404	启动器走到了旧资源索引地址
当前 profile 的版本 JSON 缺失	Fabric 启动项无法解析继承链，容易触发错误资源索引
掉电后出现	符合小型 JSON 元数据丢失的特征