环境: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'
相关片段:
"name": "fabric-loader-1.21.11"
"lastVersionId": "fabric-loader-0.18.5-1.21.11"
检查版本目录:
find ~/.minecraft/versions -maxdepth 2 -type f -printf '%P %s bytes\n' | sort
当时存在的版本文件只有:
26.1.2/26.1.2.json
26.2-pre-1/26.2-pre-1.json
26.2-snapshot-7/26.2-snapshot-7.json
26.2-snapshot-8/26.2-snapshot-8.json
缺少当前 profile 指向的:
fabric-loader-0.18.5-1.21.11/fabric-loader-0.18.5-1.21.11.json
也缺少它继承的原版:
1.21.11/1.21.11.json
根本原因
官方启动器启动 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.json1.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 元数据丢失的特征 |