McLite：轻量 Minecraft 启动器完整实现与使用指南

.minecraft
├── assets/
├── libraries/
├── runtime/
├── versions/
│   ├── <实例版本>/          # 每个实例版本独立目录
│   └── <基础版本>/          # 共享的 Vanilla / 加载器版本
└── mclite/                  # McLite 私有数据
    ├── instances/
    └── cache/

┌────────────────────────────────────────────────────┐
│ Renderer（src/ui）                                  │
│ index.html + renderer.js + styles.css               │
│ 无 Node 权限；只能调用 window.launcher.*            │
└───────────────────────┬────────────────────────────┘
                        │ contextBridge
┌───────────────────────▼────────────────────────────┐
│ Preload（preload.js）                               │
│ 白名单 API；统一 invoke / onEvent / 错误转换         │
└───────────────────────┬────────────────────────────┘
                        │ ipcRenderer.invoke
┌───────────────────────▼────────────────────────────┐
│ Main（main.js）                                     │
│ 窗口、单实例锁、IPC 路由、任务编排、事件广播         │
└───────────────────────┬────────────────────────────┘
                        │ 直接函数调用
┌───────────────────────▼────────────────────────────┐
│ Core（src/core）                                    │
│ 元数据、版本、下载、启动、实例、整合包、账户、诊断    │
└───────────────────────┬────────────────────────────┘
                        │
             文件系统 / HTTPS / 子进程

main.js                 Electron 主进程：窗口、IPC、任务编排、退出清理
preload.js              contextBridge 白名单：invoke / onEvent
src/core/
  accounts.js           本地 / Microsoft 账户存储与加密
  config.js             配置读写、字段校验、默认值
  diagnose.js           日志规则与常见问题
  http.js               HTTP、代理、重试、镜像、下载、校验
  instances.js          实例组、多版本、隔离目录、别名记录
  java.js               Java 探测、Mojang 运行时安装
  launch.js             参数构建、原生库解压、进程启动与清理
  meta.js               Mojang / Fabric / Quilt / Forge / NeoForge 元数据
  modpack.js            mrpack / CurseForge 导入
  modpackCatalog.js     在线整合包搜索、MCIM、MC百科解析
  modpackExport.js      导出 .mrpack
  scanner.js            扫描其他 .minecraft
  tasks.js              任务进度、日志事件、节流
  util.js               文件、JSON、路径、版本比较等工具
  versionCache.js       原版 ZIP 缓存
  versions.js           版本合并、库规则、安装、别名兼容
src/ui/
  index.html            外壳结构
  renderer.js           页面渲染、状态、交互
  styles.css            主题与组件样式
test/core.test.js       核心单元测试
scripts/                开发启动与截图脚本

main.js
  ├─ meta.js        ── http.js
  ├─ versions.js    ── meta.js / java.js / versionCache.js / http.js
  ├─ launch.js      ── versions.js / java.js / instances.js
  ├─ modpack.js     ── versions.js / instances.js / modpackCatalog.js
  ├─ scanner.js     ── instances.js
  ├─ accounts.js
  ├─ microsoft.js   ── http.js
  └─ tasks.js

function handle(channel, fn) {
  ipcMain.handle(channel, async (_event, ...args) => {
    try {
      const data = await fn(...args);
      return { ok: true, data };
    } catch (error) {
      console.error(`[IPC ${channel}]`, error);
      return { ok: false, error: errorPayload(error) };
    }
  });
}

function errorPayload(error) {
  return {
    code: error?.code || 'ERROR',
    message: error?.message || String(error),
    detail: process.env.MCLITE_DEBUG ? error?.stack || '' : '',
  };
}

async function invoke(channel, ...args) {
  const response = await ipcRenderer.invoke(channel, ...args);
  if (!response?.ok) {
    const error = new Error(response?.error?.message || '操作失败');
    error.code = response?.error?.code || 'ERROR';
    error.detail = response?.error?.detail || '';
    throw error;
  }
  return response.data;
}

contextBridge.exposeInMainWorld('launcher', {
  bootstrap: () => invoke('app:bootstrap'),
  createInstance: (input) => invoke('instance:create', input),
  play: (instanceId, versionKey = '', options = {}) =>
    invoke('instance:play', instanceId, versionKey, options),
  // …
});

onEvent: (callback) => {
  const listener = (_event, payload) => callback(payload);
  ipcRenderer.on('launcher:event', listener);
  return () => ipcRenderer.removeListener('launcher:event', listener);
}

_emit(force = false) {
  const now = Date.now();
  if (!force && now - this._lastEmit < 120) {
    if (!this._timer) {
      this._timer = setTimeout(() => {
        this._timer = null;
        this._lastEmit = Date.now();
        this.manager.broadcast({ type: 'task', task: this.snapshot() });
      }, 120);
    }
    return;
  }
  this._lastEmit = now;
  this.manager.broadcast({ type: 'task', task: this.snapshot() });
}

实例：Fabulously Optimized
├── 版本：Fabulously Optimized（1.21.1 / Fabric）
├── 版本：Fabulously Optimized 1.20.1（1.20.1 / Fabric）
└── 版本：原版测试（1.21.1 / Vanilla）

{
  "id": "fabulously-optimized-a1b2c3",
  "schemaVersion": 2,
  "name": "Fabulously Optimized",
  "versions": [
    {
      "key": "v-5f2c1d9a8b7e6c",
      "name": "Fabulously Optimized",
      "mcVersion": "1.21.1",
      "loaderType": "fabric",
      "loaderVersion": "0.16.x",
      "versionId": "Fabulously Optimized",
      "baseVersionId": "fabric-loader-0.16.x-1.21.1",
      "gameRoot": "C:\\Users\\<用户名>\\Desktop\\McLite\\.minecraft",
      "versionIsolation": true,
      "alias": true,
      "installing": false,
      "broken": false,
      "modpack": {
        "kind": "modrinth",
        "name": "Fabulously Optimized",
        "version": "6.x.x",
        "partial": false,
        "warnings": []
      }
    }
  ],
  "activeVersionKey": "v-5f2c1d9a8b7e6c"
}

function gameDirForInstance(gameDir, instance) {
  const root = gameRootForInstance(gameDir, instance);
  if (instance && instance.versionIsolation === false) return root;
  return versionDirForId(root, instance?.versionId || instance?.mcVersion);
}

async function createVersionAlias(gameDir, baseVersionId, desiredName) {
  const aliasId = await uniqueVersionFolder(gameDir, desiredName || baseVersionId);
  const dir = versionDirForId(gameDir, aliasId);
  await ensureDir(dir);
  const now = new Date().toISOString();
  await writeJson(path.join(dir, `${aliasId}.json`), {
    id: aliasId,
    inheritsFrom: baseVersionId,
    type: 'release',
    releaseTime: now,
    time: now,
  });
  await writeJson(path.join(dir, '.mclite-alias.json'), {
    baseVersionId,
    createdAt: now,
  });
  return { versionId: aliasId, baseVersionId, alias: true };
}

const aliasJar = path.join(versionDir, `${id}.jar`);
if (!(await statSize(aliasJar) > 0) && resolved.jarPath) {
  try {
    await fsp.link(resolved.jarPath, aliasJar);
  } catch {
    await fsp.copyFile(resolved.jarPath, aliasJar);
  }
}

const enriched = { ...alias };
enriched.mainClass = resolved.json.mainClass;
enriched.libraries = resolved.json.libraries || [];
delete enriched.jar; // 关键：不要使用 JSON 的 jar 字段
await writeJson(aliasFile, enriched);

Modules minecraft and _1._21._1 export package ... to module ...

let proxyDispatcher = null;
let proxyFetch = null;

function configureHttp(options = {}) {
  const next = normalizeProxyUrl(options.proxy);
  if (!next) return;
  const undici = require('undici');
  proxyDispatcher = new undici.ProxyAgent(next);
  proxyFetch = undici.fetch;
}

function httpFetch(url, options) {
  if (proxyDispatcher && proxyFetch) {
    return proxyFetch(url, { ...options, dispatcher: proxyDispatcher });
  }
  return fetch(url, options);
}

maven.neoforged.net    → https://bmclapi2.bangbang93.com/maven/...
maven.minecraftforge.net
libraries.minecraft.net

if (!activeProxy && mirrorPreferredHosts.has(host)) {
  return [...mirrors, url];
}
return [url, ...mirrors];

已有文件大小匹配？ → 跳过（可选校验 SHA1）
        ↓
写入 <目标>.<pid>.part
        ↓
流式计算 SHA1 + 统计字节数
        ↓
大小 / SHA1 校验失败？ → 删除临时文件，重试
        ↓
校验通过 → 原子重命名到目标路径

const temp = `${destination}.${process.pid}.part`;
const hash = crypto.createHash('sha1');
let sent = 0;

await pipeline(
  Readable.fromWeb(response.body),
  meter, // 统计进度、检测空闲超时、更新 SHA1
  fs.createWriteStream(temp, { flags: 'w' })
);

const actualSize = await statSize(temp);
const actualSha1 = hash.digest('hex');
if (expectedSize >= 0 && actualSize !== expectedSize) {
  throw new Error('文件大小校验失败');
}
if (expectedSha1 && actualSha1 !== expectedSha1) {
  throw new Error('文件 SHA1 校验失败');
}
await fsp.rename(temp, destination);

webPreferences: {
  preload: path.join(__dirname, 'preload.js'),
  contextIsolation: true,
  nodeIntegration: false,
  sandbox: true,
  webviewTag: false,
  spellcheck: false,
}

<meta http-equiv="Content-Security-Policy"
  content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';
           img-src 'self' data: https:; font-src 'self' data:; connect-src 'none';
           object-src 'none'; base-uri 'none'; form-action 'none'" />

function safeJoin(base, relative) {
  const raw = String(relative || '').replace(/\\/g, '/');
  if (!raw || raw.startsWith('/') || /^[a-zA-Z]:/.test(raw)) {
    throw new Error(`非法文件路径: ${relative}`);
  }
  const target = path.resolve(base, raw);
  const root = path.resolve(base);
  if (target !== root && !target.startsWith(root + path.sep)) {
    throw new Error(`文件路径越界: ${relative}`);
  }
  return target;
}

function redactArgs(args) {
  return args.map((arg, index) => {
    if (index > 0 && /^--(?:accessToken|session|auth_session|clientToken)$/i.test(args[index - 1])) {
      return '***';
    }
    if (/^--(?:accessToken|session|auth_session|clientToken)=/i.test(arg)) {
      return arg.replace(/=.*/s, '=***');
    }
    return arg;
  });
}

const gotLock = app.requestSingleInstanceLock();
if (!gotLock) app.quit();

function withOperation(fn) {
  return async (...args) => {
    if (busyOperation) {
      throw codedError('BUSY', '另一个安装或启动任务正在进行，请稍候');
    }
    busyOperation = true;
    try {
      return await fn(...args);
    } finally {
      busyOperation = false;
    }
  };
}

app.on('before-quit', (event) => {
  if (stoppingGamesOnQuit) return;
  if (!runningGames.size) return;
  event.preventDefault();
  stoppingGamesOnQuit = true;
  terminateLaunchedGames({ graceMs: 4000, forceWaitMs: 2000 })
    .finally(() => app.quit());
});

try {
  await installLoader(…);
  task.finish('安装完成');
} catch (error) {
  task.fail(error);
  // 回滚本次创建的别名与版本记录
  throw error;
}

{
  id: 'example-error',
  title: '示例错误',
  severity: 'error',
  patterns: [/ExampleException/i, /example failed/i],
  explanation: '一句话解释原因。',
  suggestions: ['第一步排查', '第二步排查'],
  actions: ['open-logs', 'open-mods-folder'],
}

async getVersionManifest(force = false) {
  if (!force && this.manifest && Date.now() - this.manifest.fetchedAt < 10 * 60 * 1000) {
    return this.manifest.data;
  }
  const cached = force ? undefined : await this._cachedDisk('version_manifest.json', 30 * 60 * 1000);
  if (cached) return cached;

  try {
    const data = await fetchJson(VERSION_MANIFEST_URL, { retries: 3 });
    await this._saveDisk('version_manifest.json', data);
    return data;
  } catch (error) {
    const stale = await this._cachedDisk('version_manifest.json', 0);
    if (stale) return stale; // 网络失败时仍然可以列出已知版本
    throw error;
  }
}

async _neoforgeVersions(mcVersion) {
  const legacy = mcVersion === '1.20.1';
  const groupPath = legacy ? 'net/neoforged/forge' : 'net/neoforged/neoforge';
  const metadata = await fetchText(`${NEOFORGE_MAVEN}/${groupPath}/maven-metadata.xml`);

  let versions = parseMavenVersions(metadata);
  if (legacy) {
    versions = versions
      .filter((v) => v.startsWith(`${mcVersion}-`))
      .map((v) => v.slice(mcVersion.length + 1));
  } else {
    const [, minor = '0', patch = '0'] = mcVersion.split('.');
    versions = versions.filter((v) => v.startsWith(`${minor}.${patch}.`));
  }
  return [...new Set(versions)].map((version) => ({
    version,
    stable: !/beta|alpha/i.test(version),
    label: '稳定版',
  }));
}

{
  "id": "fabric-loader-0.16.x-1.21.1",
  "inheritsFrom": "1.21.1",
  "mainClass": "net.fabricmc.loader.impl.launch.knot.KnotClient",
  "libraries": [ … ]
}

function mergeVersions(parent, child) {
  const merged = { ...parent, ...child };
  merged.arguments = {
    game: [...(parent.arguments?.game || []), ...(child.arguments?.game || [])],
    jvm: [...(parent.arguments?.jvm || []), ...(child.arguments?.jvm || [])],
  };
  if (!parent.arguments && !child.arguments) delete merged.arguments;
  if (child.minecraftArguments) merged.minecraftArguments = child.minecraftArguments;

  const libs = [];
  const index = new Map();
  for (const library of [...(parent.libraries || []), ...(child.libraries || [])]) {
    const key = libraryKey(library);
    if (index.has(key)) {
      libs[index.get(key)] = library; // 子版本覆盖父版本的同名库
    } else {
      index.set(key, libs.length);
      libs.push(library);
    }
  }
  merged.libraries = libs;
  merged.assetIndex = child.assetIndex || parent.assetIndex;
  merged.assets = child.assets || parent.assets;
  merged.javaVersion = child.javaVersion || parent.javaVersion;
  merged.logging = child.logging || parent.logging;
  merged.downloads = child.downloads?.client ? child.downloads : parent.downloads || child.downloads;
  merged.mainClass = child.mainClass || parent.mainClass;
  return merged;
}

function libraryKey(library) {
  const rules = JSON.stringify(library.rules || null);
  const natives = JSON.stringify(library.natives || null);
  try {
    const coordinate = parseCoordinate(library.name);
    return `${coordinate.group}:${coordinate.artifact}:${coordinate.classifier}:${coordinate.extension}|${rules}|${natives}`;
  } catch {
    return `${library.name || JSON.stringify(library)}|${rules}|${natives}`;
  }
}

function evaluateRules(rules, context = osContext()) {
  if (!Array.isArray(rules) || rules.length === 0) return true;
  let allowed = false;
  for (const rule of rules) {
    if (matchesRule(rule, context)) allowed = rule.action === 'allow';
  }
  return allowed;
}

检查 .mclite-installed.json 标记
        ↓ 已安装
复用现有文件，写入原版缓存
        ↓ 未安装
尝试从原版 ZIP 缓存恢复
        ↓
获取版本 JSON → 写 versions/<id>/<id>.json
        ↓
下载客户端 JAR
        ↓
按规则下载 libraries
        ↓
下载日志配置
        ↓
下载资源索引 + 全部资源对象
        ↓
整理旧版虚拟资源（virtual / map_to_resources）
        ↓
写入安装标记 + 原版缓存

async function installVanilla(meta, gameDir, versionId, options = {}) {
  const task = options.task;
  const marker = path.join(gameDir, 'versions', versionId, '.mclite-installed.json');
  const versionFile = path.join(gameDir, 'versions', versionId, `${versionId}.json`);
  const jarFile = path.join(gameDir, 'versions', versionId, `${versionId}.jar`);

  if ((await pathExists(marker)) && (await pathExists(versionFile)) && (await statSize(jarFile) > 0)) {
    await writeVanillaCache(gameDir, versionId, { task }).catch(() => {});
    return readVersionJson(gameDir, versionId);
  }

  const cached = await restoreVanillaFromCache(gameDir, versionId);
  const versionJson = cached.json || await meta.getVersionJson(versionId);

  await writeJson(versionFile, versionJson);
  await ensureClientJar(gameDir, versionId, versionJson, task);
  await downloadVersionLibraries(gameDir, versionJson.libraries, task, options.concurrency);
  await ensureLoggingConfig(gameDir, versionJson, task);
  await ensureAssets(gameDir, versionJson, task, options.concurrency);

  await writeJson(marker, { versionId, installedAt: new Date().toISOString() });
  await writeVanillaCache(gameDir, versionId, { task, force: true });
  return versionJson;
}

assets/objects/<hash 前两位>/<hash>

url: `https://resources.download.minecraft.net/${prefix}/${object.hash}`

.minecraft/mclite/cache/vanilla/<版本>.zip

cache.json   版本号、大小、SHA1、创建时间
version.json 原版版本 JSON
client.jar   客户端 JAR

const JAVA_VERSION_RE = /(?:java|openjdk) version\s+"([^"]+)"/i;

function parseJavaVersionText(text) {
  const match = String(text).match(JAVA_VERSION_RE);
  if (!match) return null;
  const version = match[1];
  const major = version.startsWith('1.')
    ? Number(version.split('.')[1])
    : Number(version.split(/[._-]/)[0]);
  return { version, major };
}

.minecraft/runtime/<组件>/<平台>/

校验账户与实例状态
        ↓
ensureInstanceFiles() 补全库 / 资源 / 日志配置
        ↓
resolveVersion() 解析继承链
        ↓
ensureJava() 选择或下载 Java
        ↓
extractNatives() 解压原生库
        ↓
classpathFor() 构建 Classpath
        ↓
buildJvmArguments() + buildGameArguments()
        ↓
spawn(javaw.exe, args)
        ↓
日志流 + 退出回调

const bootstrapManagesClientJar =
  resolved.json.mainClass === 'cpw.mods.bootstraplauncher.BootstrapLauncher' ||
  resolved.json.mainClass === 'net.minecraftforge.bootstrap.ForgeBootstrap';

if (!bootstrapManagesClientJar && resolved.jarPath) {
  entries.push(resolved.jarPath);
}

if (!userMemory) {
  const memory = Number(config.memory) || 4096;
  prefix.push(`-Xms${Math.min(1024, memory)}M`, `-Xmx${memory}M`, '-XX:+UseG1GC');
}

if (!hasLibraryPath) body.push(`-Djava.library.path=${nativesDir}`);
if (loggingPath && !hasLog4j) body.push(`-Dlog4j.configurationFile=${loggingPath}`);
if (!hasCp) body.push('-cp', classpath.join(path.delimiter));

const replacements = {
  auth_player_name: username,
  auth_uuid: uuid,
  auth_access_token: accessToken,
  user_type: isMicrosoft ? 'msa' : 'legacy',
  version_name: instance.versionId,
  version_type: resolved.json.type || 'release',
  game_directory: minecraftDir,
  assets_root: assetsRoot,
  assets_index_name: indexId,
  library_directory: path.join(gameRoot, 'libraries'),
  classpath: classpath.join(path.delimiter),
  // …
};

async function launchBinaryFor(javaPath) {
  if (process.platform !== 'win32') return javaPath;
  if (path.basename(javaPath).toLowerCase() === 'javaw.exe') return javaPath;
  if (path.basename(javaPath).toLowerCase() === 'java.exe') {
    const javaw = path.join(path.dirname(javaPath), 'javaw.exe');
    if (await pathExists(javaw)) return javaw;
  }
  return javaPath;
}

mclite/instances/<实例>/logs/mclite-<时间戳>.log

[2026-01-01T12:00:00.000Z][info][stdout] [12:00:00] [main/INFO]: ...

if (loader === 'vanilla') {
  const baseJson = await installVanilla(meta, gameDir, mcVersion, { … });
  await ensureJava(meta, baseJson, { … });
  return { versionId: mcVersion };
}

const baseJson = await installVanilla(meta, gameDir, mcVersion, { … });

if (loader === 'fabric' || loader === 'quilt') {
  versionId = await installFabricLike(meta, gameDir, mcVersion, loader, loaderVersion, task);
  await ensureJava(meta, baseJson, { … });
} else if (loader === 'forge' || loader === 'neoforge') {
  versionId = await installForgeLike(meta, gameDir, mcVersion, loader, loaderVersion, task, options);
}

const profile = await meta.getLoaderProfile(loaderType, mcVersion, loaderVersion);
const versionFile = path.join(gameDir, 'versions', profile.id, `${profile.id}.json`);
await writeJson(versionFile, profile);
await downloadVersionLibraries(gameDir, profile.libraries, task, concurrency);

下载 installer.jar（校验 .sha1）
        ↓
NeoForge：预下载安装器所需的库与 universal JAR
        ↓
写入 launcher_profiles.json（安装器要求）
        ↓
java -jar installer.jar --installClient <gameDir>
        ↓
在 versions/ 中找到新生成的版本
        ↓
补全库与日志配置

const zip = new AdmZip(installerPath);
const profile = JSON.parse(zip.readAsText('install_profile.json'));
const versionJson = JSON.parse(zip.readAsText(profile?.json || 'version.json'));
addLibraries(profile.libraries);
addLibraries(versionJson?.libraries);

const expected = loaderType === 'forge'
  ? [`${mcVersion}-forge-${loaderVersion}`, `forge-${loaderVersion}`]
  : [`${mcVersion}-neoforge-${loaderVersion}`, `neoforge-${loaderVersion}`];

const summary = inspectMrpack(zip, resolved) || inspectCurseforge(zip, resolved);
if (!summary) {
  throw codedError('MODPACK_UNSUPPORTED', '未找到 modrinth.index.json 或 CurseForge manifest.json');
}

{
  "game": "minecraft",
  "dependencies": {
    "minecraft": "1.21.1",
    "fabric-loader": "0.16.x"
  },
  "files": [
    {
      "path": "mods/example.jar",
      "hashes": { "sha1": "…" },
      "env": { "client": "required" },
      "downloads": ["https://cdn.modrinth.com/…"],
      "fileSize": 123456
    }
  ]
}

{
  "minecraft": {
    "version": "1.20.1",
    "modLoaders": [{ "id": "forge-47.4.0", "primary": true }]
  },
  "files": [{ "projectID": 123, "fileID": 456, "required": true }]
}

解析清单 → 确定 Minecraft / 加载器版本
        ↓
查找同名实例；存在则追加版本，否则新建实例
        ↓
installLoader() 安装原版 + 加载器
        ↓
createVersionAlias() + ensureVersionAliasCompatibility()
        ↓
创建隔离目录
        ↓
解压 overrides/ 与 client-overrides/
        ↓
下载清单文件（mrpack 直接下载；CurseForge 先查文件信息）
        ↓
记录 warnings / partial，完成任务

function getOverridePrefixes(kind, manifest) {
  if (kind === 'modrinth') return ['overrides/', 'client-overrides/'];
  const prefix = String(manifest.overrides || 'overrides')
    .replace(/\\/g, '/')
    .replace(/^\/+|\/+$/g, '');
  return [`${prefix}/`, 'client-overrides/'];
}

const data = await curseforgeRequest(`/mods/${file.projectID}/files/${file.fileID}`, {
  curseforgeApiKey,
  domesticMirror: domestic,
});
const info = data?.data;
if (!info?.downloadUrl) {
  missing.push({ path: info?.fileName, reason: '作者未允许第三方下载' });
}

modrinth.index.json
overrides/
  mods/
  config/
  resourcepacks/
  shaderpacks/
  options.txt

project_type:modpack
versions:<mcVersion>
categories:<loader>

const file =
  version.files.find((item) => item.primary && /\.mrpack$/i.test(item.filename)) ||
  version.files.find((item) => /\.mrpack$/i.test(item.filename)) ||
  version.files.find((item) => item.primary) ||
  version.files[0];

const targetMatch = block.match(/link\.mcmod\.cn\/target\/([A-Za-z0-9+/=]+)/);
let url = '';
try {
  url = Buffer.from(targetMatch[1], 'base64').toString('utf8');
} catch {
  continue;
}
if (!/^https?:\/\//i.test(url)) continue;

function detectLoader(versionId, json) {
  const id = String(versionId || '').toLowerCase();
  const mainClass = String(json?.mainClass || '').toLowerCase();
  const libraries = (json?.libraries || []).map((library) => versionIdFromLibrary(library.name));

  const has = (group, artifact) =>
    libraries.some((library) => library.group === group && library.artifact === artifact);

  if (id.includes('neoforge') || mainClass.includes('neoforge') || has('net.neoforged', 'neoforge')) {
    return { type: 'neoforge', version: … };
  }
  if (id.includes('quilt') || mainClass.includes('quilt') || has('org.quiltmc', 'quilt-loader')) {
    return { type: 'quilt', version: … };
  }
  if (id.includes('fabric') || mainClass.includes('fabricmc') || has('net.fabricmc', 'fabric-loader')) {
    return { type: 'fabric', version: … };
  }
  if (id.includes('forge') || mainClass.includes('forge') || has('net.minecraftforge', 'forge')) {
    return { type: 'forge', version: … };
  }
  return { type: 'vanilla', version: '' };
}

function offlineUuid(name) {
  const digest = crypto.createHash('md5').update(`OfflinePlayer:${name}`, 'utf8').digest();
  digest[6] = (digest[6] & 0x0f) | 0x30; // version 3
  digest[8] = (digest[8] & 0x3f) | 0x80; // variant
  const hex = digest.toString('hex');
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
}

请求设备代码
   ↓
用户在浏览器输入 user_code 并登录
   ↓
轮询 token 端点
   ↓
Xbox Live 用户认证
   ↓
XSTS 授权
   ↓
Minecraft 登录（login_with_xbox）
   ↓
读取 Minecraft 档案（名称 / UUID）

const DEVICE_CODE_URL = 'https://login.microsoftonline.com/consumers/oauth2/v2.0/devicecode';
const TOKEN_URL = 'https://login.microsoftonline.com/consumers/oauth2/v2.0/token';
const XBOX_USER_URL = 'https://user.auth.xboxlive.com/user/authenticate';
const XBOX_XSTS_URL = 'https://xsts.auth.xboxlive.com/xsts/authorize';
const MINECRAFT_LOGIN_URL = 'https://api.minecraftservices.com/authentication/login_with_xbox';
const MINECRAFT_PROFILE_URL = 'https://api.minecraftservices.com/minecraft/profile';

async function obtainMinecraftAccount(tokens, options = {}) {
  const xbl = await authenticateXboxLive(tokens.access_token);
  const xsts = await authorizeXsts(xbl);
  const uhs = xsts?.DisplayClaims?.xui?.[0]?.uhs;
  const xuid = xsts?.DisplayClaims?.xui?.[0]?.xid || '';

  const minecraft = await loginWithXbox(xsts.Token, uhs);
  const profile = await fetchMinecraftProfile(minecraft.access_token);

  return {
    type: 'microsoft',
    name: profile.name,
    uuid: formatUuid(profile.id),
    xuid,
    accessToken: minecraft.access_token,
    refreshToken: tokens.refresh_token || options.previousRefreshToken || '',
    expiresAt: Date.now() + (Number(minecraft.expires_in) || 86400) * 1000,
    clientId: options.clientId,
  };
}

dpapi:<base64>   Windows DPAPI 加密
plain:<base64>   系统不支持加密时的降级格式

Invalid app registration

{
  id: 'java-version',
  title: 'Java 版本不匹配',
  severity: 'error',
  patterns: [
    /UnsupportedClassVersionError/i,
    /Unsupported class file major version/i,
    /requires Java (?:SE )?\d+/i,
  ],
  explanation: '游戏或模组加载器需要的 Java 版本与当前使用的 Java 不一致。',
  suggestions: [
    '在“设置 → Java 运行时”中选择“自动选择”，让启动器匹配对应版本。',
    '如果手动指定了 Java，请改用与 Minecraft 版本对应的 Java。',
  ],
  actions: ['open-java-settings'],
}

function diagnoseText(text, context = {}) {
  const content = String(text || '');
  const issues = [];
  for (const rule of RULES) {
    if (!rule.patterns.some((pattern) => pattern.test(content))) continue;
    issues.push({
      id: rule.id,
      title: rule.title,
      severity: rule.severity,
      explanation: rule.explanation,
      suggestions: rule.suggestions,
      actions: rule.actions,
      evidence: evidenceFor(content, rule.patterns),
    });
  }
  return { issues, matched: issues.length > 0, logLength: content.length };
}

Modules minecraft and _1._21._1 export package ... to module ...

dist/McLite-1.0.0-portable.exe

npm install
npm start

$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
npm install

npm test                 # 核心单元测试
npm run capture -- .tmp/ui.png   # 渲染界面并截图后退出
npm run dist             # 构建 Windows 便携版

versions/<版本名>/
├── mods/
├── config/
├── saves/
├── resourcepacks/
├── shaderpacks/
└── logs/

Invalid app registration

%APPDATA%\McLite\accounts.json

.minecraft/mclite/cache/vanilla/<版本>.zip

cache.json   版本号、大小、SHA1、创建时间
version.json 原版版本 JSON
client.jar   客户端 JAR

.minecraft/mclite/instances/<实例>/logs/mclite-<时间戳>.log

%APPDATA%\McLite\config.json     启动器设置
%APPDATA%\McLite\accounts.json   账户与加密令牌

<启动器目录>\.minecraft\

.minecraft
├── assets/
├── libraries/
├── runtime/                 自动下载的 Java
├── versions/
│   ├── <实例版本>/          每个实例版本独立目录
│   │   ├── <版本名>.json
│   │   ├── <版本名>.jar
│   │   ├── mods/
│   │   ├── config/
│   │   └── saves/
│   └── <基础版本>/          共享的 Vanilla / 加载器版本
└── mclite/
    ├── instances/<实例>/    McLite 私有元数据、日志、原生库
    └── cache/
        └── vanilla/
            └── <版本>.zip   原版压缩缓存