Lua · 未央

一个面向 Windows、macOS 和 Linux 的独立开源 Minecraft Java 启动器。夜色侧栏加「启动台」首页：选中实例、看一眼账户和 Java，按下月光色按钮就开始游戏。

当前公开版本：0.10.2 Alpha（下载）。0.10.3、0.10.4、0.11.0、0.11.1、0.11.2、0.12.0、0.12.1、0.13.0、0.14.0、0.15.0、0.15.1、0.16.0、0.17.0 与 0.17.1 本地实现和独立源码审核已完成，待各自提交的三平台发行验收。

0.10 有什么

• 启动：原版版本浏览器包含正式版、快照和远古版本，已实现旧参数与资源布局适配，实际兼容组合仍须逐一验证；Fabric 支持 1.14 起的受支持版本与快照；Forge、NeoForge 保持 1.20.1 起的正式版。游戏崩溃时自动分析可能原因。缺少 Java 时自动下载官方运行时，内存自动分配，每个实例可单独设置 Java、内存、JVM 参数和窗口。
• 正版登录：Microsoft 账户登录，校验 Java 版所有权与游戏档案，头像显示正版皮肤。Minecraft 官方 API 接入已于 2026-10 获批。
• 内容：Modrinth / BBSMC（实验性）模组按分类搜索安装并自动处理必需依赖；资源包与光影下载；.mrpack 整合包在线安装或本地导入；单个模组启用 / 禁用。
• 世界：地图预览（主世界 / 下界 / 末地）；查看世界信息与种子；完整备份、恢复为新世界、导出 ZIP；导入网上下载的地图。
• 实例：复制、删除（移到回收站）、独立设置。
• 下载与更新：国内镜像（BMCLAPI）自动切换；启动器内检查并安装新版本。
• 外观：浅色 / 深色 / 跟随系统。

隐私：没有统计和遥测，详见 隐私政策。Windows 签名计划见 代码签名说明。

验证状态

更新：2026-10-24。

• 公开发行：0.10.2 的发行运行 39734466434对应提交 9432352ad31621fbcbeaf6d39494691d8f1630dc，Windows x64 / macOS ARM64 / Linux x64 的测试、构建和打包成功，公开四项 EXE / DMG / ZIP / AppImage 资产。签名和公证尚未配置。
• 当前基线：主分支 cad65ec 只纠正说明和官网文字，产品代码与上述发行包一致；本轮重新运行基线全部 568/568 自动测试通过。新补丁仍须单独测试、审核和当前提交 CI。
• 已有 macOS 实测：2026-10-22 已记录完整 Microsoft → Xbox / XSTS → Minecraft 登录、所有权/profile、0.10.0 正式包原版 1.21.1 启动、重启后恢复会话并再次启动；应用内下载、校验并打开 0.10.1 DMG 也有记录。本轮读取这些记录，没有重复登录或运行游戏，详见登录说明。
• 仍待实机验证：Windows / Linux 游玩、广泛旧版/加载器/整合包组合、真实世界恢复、长期游玩与实际联机。主菜单可见多人游戏/Realms 入口，不代表联机已测试。
• 官网：已在既有 Render 静态站同步 0.10.2，核对 live、HTTP 200、HTML 与仓库逐字节一致，以及真实 Release 入口。

0.10.3 已在本地修复世界恢复的目录竞争与 macOS 内存重计：完整585项、独立相关79项和构建通过，本地未签名macARM包核对通过；尚未公开，不复用旧CI。见开发日志和独立审核。0.8–0.10的专门独立记录缺口保留，不补造历史执行证据。

0.10.4 已在本地修复更新包短写、共享暂存、响应流清理与版本选择竞态，并加入更新与活动工作互斥。完整623项、独立相关46项、生产构建和本地未签名macARM包核验通过；生产下载器实际下载公开DMG并独立核对磁盘摘要，未运行安装程序。当前提交三平台CI、原生自更新和发行资产另验，见开发日志和独立审核。私有更新资料与AppImage旧副本保留占空间，尚无自动清理。

0.11.0 新增明确所选世界的数据包列表、声明详情和本地ZIP只读预览，尚无安装/启停。完整667项、独立新增44项（含相关更新门54项）和生产构建通过；隔离Electron窗口/生产IPC验22项分页、跨实例迟到与34项源/state不变，文件选择回调有明确注入，不当作真实OS picker或游戏加载验收。用法与格式限制见数据包说明、开发日志和审核。当前提交CI/发行另验。

0.11.1 新增Modrinth数据包搜索、项目/版本和文件/依赖声明；只浏览元数据，尚无内容下载或安装。完整701项、独立新增34项（相关60项）、构建及本地包核验通过；真实生产Core官方3GET与隔离Electron流程分别留痕，原生UI的HTTP/打开站点端口为明确注入。见发现说明、开发和审核。当前提交CI/发行另验。

历史开发验证（0.3–0.7.1）

以下保留截至 2026-10-21 的原场景和当时未完成项；其中“待审”“公开0.3”“上传0.4中”等仅属历史状态。0.4 已发布，0.5–0.7.1 功能已随 0.8 合并公开，当前状态以上节为准；没有做过的历史实机或审查不追溯补造。

• 0.7.1 当前验证：新增清单 7、事务 27、Core 19 项独立合跑 53/53，全仓 517/517 与生产构建通过。集成者使用生产 Core 和原创文件树验证完整目录备份、按清单独立重建、逐文件 hash、完成凭据、实际复制中取消、跨实例列表/打开隔离；初始化后 50 项源文件、目录和 launcher.json 的字节、mode/mtime/ctime/inode 不变。没有读取用户实际世界、运行 Java、认证或游戏。测试桥已验证确认/任务/取消/跨实例状态；最终未签名 macOS ARM64 包的版本、架构、hash 与构建内容已核对，原生与当前提交 CI/发布未验，详情见 0.7.1 开发记录。

• 0.7.0 本地验证：全仓 464/464 测试、类型检查与生产构建通过；新增 NBT 15、文件读取 31、Core 19 项，独立重跑 65/65。验证使用原创 gzip/NBT 夹具和真实临时目录，没有读取用户实际世界、执行 Java、认证或游戏。来源切换迟到请求回归已修复。真实游戏生成样本、原生桌面、当前提交三平台 CI 与公开发布尚未验证；集成者生产 Core/原创夹具测试桥完成主旧来源、慢请求切换、种子查看隐藏与跨实例隔离，24 项只读基准不变；最终未签名 macOS ARM64 包的版本、架构、SHA-256 与构建内容核对通过。详见 0.7.0 开发记录，公开仍为 0.3.0。

• 0.6.2 本地验证：全仓 399/399 确定性测试通过，新增事务 30、Core 22 项，独立重跑 52/52。真实 Core/隔离文件测试桥完成检查、禁用/恢复、冲突与外部编辑保护、历史来源、选择刷新和跨实例后台状态；不是原生 Electron 验收。未联网、解析/执行 JAR、运行 Java、认证或游戏。最终生产构建和未签名 macOS ARM64 DMG/ZIP 的版本、架构与 SHA-256 核对通过；112 条第二页改名/恢复及定位保持通过。无桥仅 SSR/源码边界已验，完整无桥浏览器、原生、当前提交三平台 CI 与发布仍待。见 0.6.2 开发记录。

• 0.6.1 本地验证：全仓 347/347 确定性测试通过，新增 catalog 23、安装事务 30、Core 接线 17 项，独立重跑合计 70/70。生产 Core 在隔离实例中真实下载 Modrinth Fresh Animations（743793 字节）及 Complementary Reimagined（553397 字节），声明双 hash 校验、固定目录归位、历史下载登记及再次安装复用通过。没有运行 Java、认证或游戏，不代表渲染前置齐全或已启用；生产 Core 两来源两类型真实搜索均通过，BBS 光影页省略 1 项其他类型而显示 19 项；BBS 浏览器预览因 Failed to fetch 显示错误、真实 CDN 下载仍未验证。最终类型检查/生产构建与隔离真实 Core 测试桥验收通过；晚修后未签名 macOS ARM64 DMG/ZIP 的版本、架构与 SHA-256 核对通过；原生界面、当前提交三平台 CI 与发布尚未完成。详见 0.6.1 开发记录。

• 0.6.0 本地验证：277 项确定性测试、类型检查及生产构建通过。只读 HTTP 测试桥连接真实 Core 与隔离目录，已验证四类清单、历史来源和禁用后缀详情、世界未读 NBT 说明、实例切换、103 条记录分页、搜索回到第一页，以及打开文件夹的忙碌与跨实例迟到错误隔离。另已验证同实例文件夹失败可重试、Home/End 标签操作，以及无 bridge 预览不生成清单。扫描与界面操作不写游戏内容，未触及用户实例，不是原生 Electron IPC 或系统文件管理器验收；原生桌面与当前提交三平台 CI 待验。

• 0.5.0 本地验证：245 项确定性测试及生产构建通过。浏览器预览已验证实例草稿切页保留、非法堆参数拒绝，以及 6144 MB 内存、1600×720 窗口、关闭全屏、含空格系统属性的保存和刷新后摘要；全局 GC/含空格属性、1920 宽、强制全屏保存后，恢复默认再刷新，各项回到默认且实例 6144 MB 覆盖保留。浏览器结果不代表原生 Electron 或真实游戏已通过；0.5 原生桌面验收、当前提交三平台 CI 与公开发布待完成。

• 分发状态：0.4–0.7.0 的本地构建和未签名 macOS ARM64 包证据见各版本开发记录，0.7.1 最终包的版本、架构、hash 与构建内容已核对。GitHub 浏览器登录已恢复，正在上传 0.4 源码；对应 CI/Release 尚未完成，当前下载仍指向实际已发布的 0.3.0。本地结果、源码上传和旧提交绿灯都不等于新版本三平台发布成功。

已实现

• 独立实例：各自的游戏目录、存档与模组，共享校验后的基础资源。0.5 增加重命名和逐项继承/覆盖的运行设置，草稿跨页保留；当前选择仅记在本机或当前浏览器。
• 0.6 增加四类实例内容的只读清单：真实一层文件/目录、搜索排序、分页、刷新和元数据详情；不执行资源、不推断兼容性或游戏加载状态。
• 0.6.1 增加资源包与 Iris / OptiFine 光影：选实例与发布、重新核对文件、SHA-512 必需/可选 SHA-1 校验、固定目录放入、取消和同字节复用；不自动启用。
• 0.6.2 增加模组详情单文件禁用与恢复 .jar，带二次检查、无覆盖改名、恢复标记和同实例互斥；安装/升级保护禁用伙伴，不自动联动依赖。
• 0.7 增加明确选定世界的只读 NBT 字段和按需种子；主文件/旧副本独立，未知字段不补默认值，读取不保存状态或世界内容。
• 0.7.1 增加明确确认后的完整目录备份、逐文件清单校验、会话任务与历史完成列表；本地确定性测试与原创树测试桥通过，不包含 ZIP、恢复、自动备份或删除。
• Minecraft 正式版本列表，现代版本（1.20.1 起）的下载与 SHA-1 校验。
• Fabric / Forge / NeoForge 安装，选择对应的加载器版本；Forge / NeoForge 在本机 Java 下运行官方安装器中的处理步骤并校验产物。
• 选择 Minecraft 与加载器后直接下载；任务页展示进度、取消、重试与已完成文件复用。
• Modrinth / BBSMC 整合包在线搜索、版本选择和下载；本地 .mrpack 导入前预览名称、版本、加载器与文件大小。
• 整合包固定加载器版本、验证 SHA-1 与 SHA-512、应用客户端配置；取消或失败后可从任务页重试，完整安装成功才标记为可启动。
• Java 自动探测、官方运行时自动下载与安装、手动路径；切换自动模式会保留手动路径。设置页可提前下载 Java 17 / 21 / 25，任务页显示实际进度、取消与重试。
• 自动 / 手动内存与并发设置；启动前重新计算内存分配。
• 游戏启动、关闭、状态跟踪与实时日志。
• Microsoft设备码认证、授权进度和倒计时、取消、许可与档案检查、刷新令牌安全存储；Lua自有应用已获批，macOS完整登录/原版1.21.1启动与重启恢复有记录，不能把历史403继续当作当前待审状态。
• 仅支持经过完整验证的 Microsoft 账户启动；没有离线入口、离线 IPC 或登录失败后的离线回退。旧版本的离线账户文件不会被加载。
• Modrinth / BBSMC 实时搜索；根据实例的游戏版本与加载器匹配模组，下载同一来源的必需依赖。
• 模组页提供 19 个功能分类，分类、关键字、游戏版本及加载器条件共同生效，自动映射各资源来源的分类值。

0.3.0 模组功能分类

0.3.0 的分类筛选包含性能优化、世界生成、冒险探索、科技、魔法等 19 个 Modrinth 官方模组类别。搜索请求使用原站分类条件：Modrinth 使用英文键，BBSMC 使用对应的中文分类值；分类会与关键字、游戏版本及加载器条件共同生效。

分类定义、来源映射和筛选界面均已实现，两站的“性能优化”真实查询已完成上述抽样验证。分类反映资源站的项目标签，不会自动分析某个模组的全部功能，也不表示结果一定适合所有实例。

实例设置（始于0.5，已随公开版本交付）

在版本列表点击齿轮，或点击首页“此实例运行环境”。常用设置可重命名实例、选择继承全局或指定 Java、设置内存方式及手动上限；高级设置提供 JVM 参数、游戏窗口宽高与全屏。重命名只改变显示名称，不移动目录。恢复继承后，下一次启动采用全局值；未设置的项目使用启动器默认值。

JVM 参数每行一个完整参数，包含空格的值不需要 shell 引号，非空行的空格、引号和反斜线原样保留。实例参数整体替换全局列表；选择“本实例替换”并留空可明确清空。内存、类路径、认证和启动入口等受管参数不能自行覆盖，不支持的参数在保存时报错。全屏“关闭”是明确覆盖；恢复继承且全局未指定时沿用游戏设置。

草稿在本次应用会话内按实例保留，关闭设置页或切页不会丢失；尚未保存的草稿不承诺在刷新或重启后恢复。保存期间相应实例不能重复提交，失败保留草稿并允许重试。“撤销到已保存设置”和“全部恢复继承”是不同操作，恢复继承仍须保存。全局 JVM 与窗口设置可在“启动器设置”中恢复默认。当前实例选择会在本机记忆，浏览器预览与桌面版各自保存，不跨设备同步。

0.9已增加复制和可恢复删除；导出、归档、复制范围选择和完整资源管理仍待后续实现。基础清单范围如下。

实例内容（始于0.6）

从版本行的“实例内容”按钮或底部“内容”进入，选择当前实例和分类：

分类	实例内实际目录
模组	game/mods
资源包	game/resourcepacks
光影包	game/shaderpacks
世界 / 地图	game/saves

只列出一层文件和目录，可按文件名搜索、按名称或修改时间排序、刷新和分页。点击条目在同页查看相对路径、类型、修改时间及普通文件大小。目录大小显示“未统计”；清单扫描不读取 NBT，0.7 在选中世界目录后提供下述独立的只读详情。

“曾登记来源”仅表示历史下载记录，不证明当前文件通过哈希校验；“禁用后缀”仅表示 .disabled 文件名，不判断实际加载、依赖或兼容性。扫描有条目数与时间预算；出现跳过或截断提示时，搜索和排序只针对本次已读记录。安装中暂停扫描，运行中只读查看且文件可能变化。

清单扫描仍只读；0.6.2 在模组详情单独提供下述确认改名动作，不提供更新、删除或批量管理。0.6.1 的资源下载与自动归位由单独的“资源包与光影”入口执行；世界数据包管理仍未实现。普通浏览器预览不能读取本机目录，不生成示例内容。此版本的测试桥只用于隔离验收，不随软件作为访问本地磁盘的网页服务发行。

世界只读详情（始于0.7）

选择当前实例“世界 / 地图”中的一个目录，按需读取固定的 level.dat。可明确切换到 level.dat_old 查看旧副本；两者不合并、不自动回退，旧副本也不是完整备份。关闭游戏并等待启动准备、安装和设置保存结束后可读取，error 状态实例也可查看，不触发模组恢复清理。

详情显示文件中有效记录的世界名称、保存版本、DataVersion、游戏模式、难度、硬核、允许命令、Time / DayTime 与 LastPlayed。文件夹修改时间另列，不当作最后游玩；原始 tick 不换算成实际游玩时长。缺失或类型不符时显示未知/部分读取，损坏或超过预算时不显示已解析的局部值。世界大小仍不递归统计。

种子默认不随详情返回。点击“查看种子”会重新读取同一来源并核对快照，显示后可隐藏或主动复制；显示时可能进入截图，复制后会进入系统剪贴板。刷新、切来源或切世界会清除界面种子；文件改变或两分钟读取凭据过期时须刷新，不自动取旧副本种子。世界原始数据与种子不写日志、状态或诊断记录。

本版只接受 gzip 与有界大端 Java NBT，字符串采用 canonical Java modified UTF-8；比宽松 DataInput.readUTF 可接受的非规范编码范围窄。压缩文件上限 8 MiB、展开上限 32 MiB，并限制深度、条目和合作式读取时间；超限不表示世界一定损坏。Minecraft 26.1 的同文件嵌套难度/硬核可读取，但迁移到独立文件的种子和时钟不追读，故为局部支持。当前只有原创夹具证据，真实游戏生成样本尚未验证。

世界详情不解析区域、玩家、数据包或图标，也不做恢复、导出、删除或 NBT 编辑；目录备份为下述独立动作。只读快照不证明世界完整、兼容或可以安全启动；它也不能保证外部游戏进程运行时的一致快照。普通浏览器预览不能读取本机世界。

手动世界目录备份（始于0.7.1）

在“实例内容 → 世界 / 地图”选择一个普通目录，确认所有打开此世界的游戏与服务端均已关闭后，创建新的本地目录备份。Lua 不能证明其他启动器或命令行进程已关闭；不会宣传运行中热备安全。目标固定为 Lua 数据目录的 backups/worlds/<实例ID>/<备份ID>/world/，不会让网页传入任意磁盘路径。

备份按原字节复制全部受支持的普通文件和空目录，包括 session.lock、隐藏项及新布局文件，不解析或执行附带内容。生成逐文件 SHA-256 清单，读回目标，再二次读取源文件和目录清单；核对完成后才发布完成凭据。源中的链接、特殊文件、硬链接、多卷嵌套、名称冲突或超预算会明确失败，不跳过后称完整。当前上限为 100 GiB 总量、32 GiB 单文件、100000 条目；空间预检不等于空间预留。

全局一次只运行一个备份，与同实例的启动、安装和设置保存互斥。任务支持按操作 ID 取消，切页后可在任务页查看；取消等待已发出的文件操作结算才释放运行中的任务锁。成功提交后的迟到取消不撤销完成结果，提交状态无法确认时要求人工检查。退出应用只请求取消，尚未验证原生退出会等待全部文件操作结算。

目录备份失败或取消后保留未完成资料，并提示仍占空间；列表仅核对历史完成凭据和清单，不会重新校验当前备份的全部内容。原目录被换成同名世界时，历史记录不证明它仍是同一世界。0.8另增已完成备份的流式ZIP导出与完整回读，0.9另增恢复到选定实例的新世界和本地地图ZIP导入；自动备份/保留策略仍未实现。0.10.2恢复提交的目录竞争已在本地0.10.3修复，尚待发行，当前影响见已知问题。

备份包含世界/玩家/种子等原始私密数据，仅保存在本机，不自动上传。原创临时树的成功不代表真实游戏世界、不同卷、网络文件系统、任意断电耐久或原生桌面已验收；关闭外部游戏和保留其他独立备份仍是必要条件。

单个模组文件禁用与恢复（0.6.2 开发版）

在已安装完成且关闭游戏的 Fabric / Forge / NeoForge 实例中，选择一个普通 .jar 或 .jar.disabled 文件，先检查原名和目标名，再确认“禁用文件”或“恢复 .jar”。操作只改变固定 game/mods 中这一个文件名，不改字节、不解析 JAR、不联动依赖；下次启动是否能加载仍须单独验证。非规范大小写后缀、目录和链接不支持。

检查结果有效 120 秒，实例变化、退出或提交后失效；过期或外部编辑时刷新清单重新检查，不自动重试旧确认。冲突文件不会覆盖或合并。历史下载登记保持原字节，禁用后不通过后缀猜来源，恢复精确原名后可再次显示曾登记来源。安装新版本或必需依赖发现已有禁用伙伴时会先拒绝，不悄悄重新启用。

无法安全回滚会保留 .mod-toggle-* 恢复资料并阻止后续启动、安装和实例设置写入。双文件、空标记或损坏记录需要保留并人工检查，处理后重启再检查；不要盲目删除任何一份文件。只清理能明确确认结果的记录，不承诺任意断电恢复。

资源包与光影（0.6.1 开发版）

在“资源包与光影”选择 Modrinth 或 BBSMC，搜索后明确选择目标实例和发布。资源包按所选 Minecraft 版本与 minecraft loader 查询；光影仅接受 iris / optifine 发布，不以 Fabric / Forge 代替渲染方案。项目所需前置仍须查看作者说明，空依赖列表不保证无需前置。

主进程重新核对项目、版本和选中文件名/hash，只下载受支持来源的明确主 ZIP；无 primary 时只接受唯一主 ZIP。文件保留 ZIP 格式，分别放入 game/resourcepacks 与 game/shaderpacks；不解压、不改 options.txt 或渲染配置，文件放入不代表已启用。任务支持真实进度与取消，失败可重新选择发布重试；同版本相同内容校验后复用，不覆盖冲突文件或自动更新其他版本。

SHA-512 必需，提供 SHA-1 时同时校验，单 ZIP 上限 512 MiB。网盘/外站、附带资源包、多个不明确候选、Canvas / Vanilla 光影或必需/不兼容依赖等不自动安装，显示官网获取。BBSMC 验证网页、登录或付费限制不会绕过。

内容页中的来源、下载日期、大小与 hash 是历史登记，本次只读清单不重新校验当前字节；也不证明兼容性或实际加载。地图、世界数据包、本地资源 ZIP 导入、资源包/光影自动启用、更新回退和删除不在资源下载范围；0.6.2 的单模组改名独立于此功能。

自动内存

默认采用自动分配。主进程读取系统总内存，优先使用 process.availableMemory() 返回的当前可用内存，在运行时和平台支持的范围内考虑可回收内存及进程限制；无此 API 时回退到 os.freemem()。不同平台的统计口径可能不同，这些值是启动前的快照。

建议值结合游戏版本、是否使用模组加载器和所选 Java 的位数，并为操作系统、Java 非堆内存及其他程序保留余量。现代原版以 4 GB、模组环境以 6 GB 为起始建议，实际分配可能因内存压力下调；这不是 Mojang 最低配置，也不能代替大型整合包自己的要求。

手动模式会保留你填写的偏好值，但本次启动仍受当前安全上限约束，不会直接把全部内存交给 Java。低于最低 1 GB 堆预算时拒绝启动并提示释放内存；32 位 Java 的堆限制为 1 GB。界面的建议值会在启动时重新计算，不能保证游戏过程中不会发生内存不足。

本地运行

准备 Node.js 22.12+ 和 pnpm 11.25，然后：

pnpm install
pnpm desktop

Java 自动管理会读取每个游戏的官方 javaVersion.majorVersion 与 component，优先使用匹配的本机或托管 Java，缺失时下载 Mojang 运行时。以实际版本清单为准，例如 1.20.1 需要 17、1.20.5 需要 21、26.3 需要 25。可在设置中提前准备 17 / 21 / 25，或选择自己的 Java 可执行文件。

运行时保存在 launcher/runtimes/，不改系统 PATH 或 JAVA_HOME。下载验证清单和每个文件的大小及 SHA-1，完成权限准备、版本与架构探测后才提交。Linux ARM64 等官方未提供的组合会明确提示手动选择，不会偷偷换架构。下载页任务记录限当前进程；重启后复核并复用已安装运行时，尚不提供字节级续传。

pnpm dev       # 浏览器 UI 预览，不能启动 Java
pnpm check     # TypeScript
pnpm test      # 使用模拟服务的确定性测试
pnpm build     # 前端 + Electron
pnpm package   # 当前系统未打包目录
pnpm dist      # 当前系统安装包

浏览器预览与桌面版有明确区分。预览实例仅保存在浏览器中，不会被当作已安装游戏。

Microsoft 登录

当前构建默认内置 Lua 自己注册且已获准接入 Minecraft API 的公开 Microsoft 应用 ID，普通玩家无需注册应用。macOS 已记录完整正版登录与原版 1.21.1 启动，其他平台实机范围另验。维护者或独立 fork 请参阅 完整接入步骤与验证记录，可通过 LUA_MICROSOFT_CLIENT_ID 覆盖构建配置。高级设置只保存公开 Client ID；不要填写 Client Secret。

登录在 Microsoft 官方页面完成，Lua 不收集 Microsoft 密码。访问令牌仅在 Electron 主进程内存中处理；刷新信息通过系统安全存储加密后写入应用目录。系统密钥环不可用时拒绝持久化，不降级为明文。

启动时由主进程取得有效 Minecraft 凭据；同一进程可复用尚未到期的访问令牌，需要刷新时重新完成认证、许可与档案检查。重启后必须在线刷新，不能仅凭缓存的用户名启动。退出账户或服务明确报告授权、所有权或档案失效时，会清除对应会话并要求重新登录。网络失败不会生成临时身份。

从旧版本升级不会主动删除游戏实例或存档；旧 offline-account.json 不再读取。2026-10-21 提交的接入申请已于 2026-10-22 确认获批，历史 403 不能继续当作当前状态，也不能把之后所有 403 都归因于审批。

整合包

在“整合包”页面选择 Modrinth 或 BBSMC 并搜索项目、选择发布版本，或导入本地 .mrpack。当前支持 Minecraft 1.20.1 及之后的正式版和原版 / Fabric / Forge / NeoForge；具体加载器必须有对应游戏版本的官方发布，包中声明的加载器版本会固定使用。公开0.10.2仍将 optional 客户端文件一并安装。0.13.0本地实现改为先预览文件与来源、分页选择最终有效的 optional 下载，默认全选但可取消；必需与包内覆盖文件锁定，服务端和被覆盖来源不写入。确认前不创建实例或准备游戏/Java，选择会在安装前保存并用于重试。见可选下载用法。

Quilt、旧游戏版本和 CurseForge 格式会给出明确的不兼容提示。.zip 只有包含 Modrinth 标准清单才可导入。每个包创建独立实例，配置覆盖不会写入其他实例；失败后保留包源，可在“下载任务”中重试。新增 Forge / NeoForge 的安装流程已做上述代表性版本实测，完整整合包和游戏运行矩阵仍待补齐。

BBSMC 接入

BBSMC 提供可匿名读取的 https://api.bbsmc.net/v2 接口，搜索与项目版本字段兼容 Modrinth v2。Lua 独立调用公开 HTTP 接口，没有复制站点源码，也不是 BBSMC 官方客户端。官方实现见 bbsmc/app。

• 模组、整合包和 0.6.1 资源包/光影页面可切换来源；搜索、版本选择、依赖解析与安装记录分别使用所属来源，不会因项目 ID 相同而混用。
• BBSMC 模组/整合包直接安装只接受其 cdn.bbsmc.net 上受支持且具备校验值的 .jar 或 .mrpack；0.6.1 资源包/光影主 ZIP 另要求 SHA-512、提供 SHA-1 时同时验证。包内文件仍受路径、来源域名、大小和哈希限制。
• 网盘、外部站点链接、没有校验值的占位发布，以及不支持的格式显示“官网获取”。401 / 403 提示前往官网处理访问权限；不登录 BBSMC 账户、不绕过购买或资源访问限制。
• CDN 返回网页安全验证时也会拒绝安装，并提示前往官网；不能将搜索 API 可用等同于文件下载畅通。
• 当前接入为实验性，未承诺公开 API 的长期兼容或站点可用性。仅在用户搜索、选版本或安装时请求，不进行整站采集。接口限流或不可用时显示错误，由用户稍后重试。

获取构建

软件免费公开下载，源码采用 MIT 许可。打开 GitHub Releases，在 Assets 获取已完成发布的平台安装包；各平台构建与发布状态以 GitHub Actions 和 Release 实际附件为准。构建尚未代码签名或公证，仍属于 Alpha 测试版。

Lua 安装包不捆绑 Minecraft 游戏、模组或整合包；安装时从对应发布来源下载。Java 可按需从官方自动下载，也可自行安装；Minecraft Java 游戏许可需要由玩家持有。

数据与隐私

默认数据位于系统的 Lua 应用数据目录下 launcher/，实例存档在 instances/<id>/game/。不会自动扫描或修改其他启动器的游戏目录。没有分析统计、广告或账号遥测。

下载和搜索会连接 Mojang / Microsoft、Fabric、Forge / NeoForge，以及所选来源 Modrinth / BBSMC 的官方服务。资源信息与图标来自对应站点 API，版权归各项目作者；不随仓库重新分发这些素材。

兼容性与限制

• 跨平台架构及打包配置已提供；实际验证范围见上方“验证状态”，Windows / Linux 游戏运行仍待测试。
• 旧版 Minecraft / 快照适配与启动器更新已于 0.9 / 0.10 实现；实际平台兼容矩阵仍待补。Quilt、CurseForge 包、整合包导出、完整皮肤/披风管理、世界数据包与自动备份尚未实现。
• 当前公开 0.10.2 的世界恢复目录竞争、macOS 内存重复计数已在本地 0.10.3 修复，更新器文件写入与协调问题已在本地 0.10.4 修复；两版尚待发行，具体范围以版本说明及已知问题为准。
• Forge / NeoForge 只完成有限版本的真实安装验收，不能据此承诺所有加载器版本、模组组合或系统均可正常游玩。
• 模组更新、卸载和冲突分析尚未实现。Alpha 阶段建议新建测试实例。
• 安装包尚未做 Windows 代码签名或 macOS 公证。开发者需要自行配置签名后正式分发。
• Lua 与 Minecraft、Mojang、Microsoft、PCL、HMCL、Modrinth、BBSMC 均无官方关联。

开发

src/                React UI 与受限的桌面 API 客户端
desktop/core.ts     安装、平台规则、Java、启动与资源来源
desktop/loader.ts   Forge / NeoForge 元数据、安装器与产物校验
desktop/memory.ts   系统内存采样、自动建议与启动堆限额
desktop/instance-options.ts 实例参数校验与逐项配置继承
desktop/game-window.ts 游戏全屏设置的有界文件更新
desktop/java-runtime.ts 官方 Java 下载、校验、发现与共享任务
desktop/launch-preparation.ts 凭据获取之前的启动取消与退出保护
desktop/auth.ts     Microsoft → Xbox → Minecraft 认证
desktop/modpack.ts  Modrinth 包格式、路径与归档校验
desktop/resource-catalog.ts 资源项目/发布兼容与选中文件校验
desktop/resource-install.ts 资源 ZIP 下载、事务与历史登记
desktop/resource-inventory.ts 实例资源的一层只读清单
desktop/nbt-reader.ts 有界 Java NBT 白名单投影
desktop/world-details.ts 固定世界文件只读快照与字段检查
desktop/world-types.ts 世界详情与按需种子的受限 DTO
desktop/world-backup.ts 完整目录复制、双向校验与完成凭据
desktop/world-backup-manifest.ts 备份清单、路径树和历史摘要校验
desktop/main.ts     Electron 生命周期、IPC 与系统安全存储
desktop/preload.ts  隔离的命令桥
src/mod-categories.ts 模组功能分类及资源来源映射
docs/RESEARCH.md    功能参照与源码许可研究

Electron 禁用 renderer Node 集成、启用 context isolation / sandbox、验证 IPC 来源并限定命令。下载仅允许指定官方域名，验证校验值并拒绝路径穿越。测试使用临时目录与模拟网络响应，不依赖个人账号。

原创代码采用 MIT 许可。依赖保留各自许可，见 第三方说明。贡献请参阅 CONTRIBUTING.md。

每个小版本的变更见 CHANGELOG，详细开发日志见 docs/devlog，独立审查见 docs/reviews。完整需求与状态见 功能矩阵，每个验证等级的边界见 验收矩阵。

0.11.2 新增本地/Modrinth数据包的明确世界安装：文件检查、一次性确认、完整新备份、无覆盖归位与重启保护。完整777项、独立205项、构建与本地包通过；原创夹具的生产Electron IPC/文件系统流程已验，HTTP/ZIP/picker明确注入，没有运行游戏。新增准确1.20.1/1.21.1官方格式证据，其余未知范围不强制安装。见安装用法、开发和审核；本版尚未公开。

0.12.0 新增已安装/禁用后缀JAR的模组声明和本地只读预览：Fabric/Quilt JSON、Forge/NeoForge TOML、多模组、依赖与外层摘要分别展示，不导入或执行。完整850项、独立176项、构建及本地包通过；生产Electron原创夹具流程11项源/state不变，picker注入，尚无本提交CI或公开资产。见用法、开发及审查。

0.12.1 新增明确实例的单个本地模组导入：选择JAR后完整检查受支持载荷、核对当前启用/禁用ID与别名、依赖和历史禁用伙伴，再确认关闭游戏并仅新增到 game/mods。首版只接纳可解释的Fabric1、Forge javafml数字版本条件；未知Java要求、NeoForge/Quilt、嵌套与复杂声明会阻止导入，无强制绕过或自动前置求解。928项完整测试、254项独立相关测试/探针、构建及未签名macARM包核验通过。生产Electron原生IPC/真实文件系统完成Fabric与Forge导入、2份回执独立重建，11个源/state文件保持不变；仅picker回调注入，原创惰性JAR与安装profile记录不是实际游戏安装、OS对话框或游戏验证。本提交CI/公开资产仍待。保留暂存与完成凭据占额外空间，不覆盖原文件、不替换已有模组，也不将CRC/hash当代码或签名认证。见导入用法、开发及审查。

0.13.0 已在本地实现本地/在线 .mrpack 统一文件计划与可选客户端下载选择，包含路径搜索、每页100条、来源角色/覆盖链、全包全选或清空及摘要统计；只在确认后创建独立实例。选择schema、归档hash与规划摘要先持久化，取消/失败和重启重试沿用确切选择；旧无记录未完成实例明确保留全装。完整991项（新增63项）及构建通过，主JS545.72kB/gzip163.66kB的默认体积提示保留。生产Electron真实main/preload/Core/安装文件流程已验7项，明确空选择只写必需与客户端覆盖；HTTP/picker与9次Java属性回调均为原创替身，未执行Java或游戏。独立139项（63新增受管+9原创探针+67不重叠旧相关）通过，范围内无未修阻塞；未签名macARM包的版本/架构/hash与ASAR六文件核验通过，包未执行；1240浅色与920深色完整视口和各内容区宽度复核均无横向溢出。当前提交CI/公开资产、真实OS选择和实际整合包游戏另验。私有缓存只清理本进程证据完整的闲置副本，未知/历史资料保留；整包原有事务不冒充单JAR事务或完整崩溃审计。见用法、开发和审核。

0.14.0 已本地完成独立的PNG皮肤收藏：检查后预览、明确Classic/Slim、正反面/外层/背景/整数缩放，以及标签搜索、24项分页、改名、改模型、导出和仅索引移出。现代64×64支持两模型，旧64×32仅Classic镜像预览；只支持明确的8bit非交错PNG范围。无需登录，不改变当前账户或提供离线身份；不上传皮肤、操作披风或获取外部图片。完整1056项（新增65项）、独立112项及构建通过，两项实际P2（历史备份链接和NFC扩张写出无效索引）已修复并复验。主JS547.57kB/gzip164.49kB的默认提示保留，本地皮肤页独立延迟加载；不把分包当完整性能验收。生产Electron真实main/preload/Core/PNG/图库/布局与原创文件系统验7项，6个源/世界账户哨兵与状态文件不变，实际导出规范PNG12439B并保留2个blob；仅原生打开/保存回调注入，0HTTP/进程/Java/游戏调用，无真实认证、账户写入或纹理下载。920px各容器宽度及重启后深色控件已复核；未签名macARM包版本/架构/hash与ASAR八文件字节匹配，完整PNG许可在源码、最终bundle与随包notice核同，包未执行。本提交CI/公开发行和真实OS/游戏另验。见本地皮肤用法、开发与审核。

0.15.0 启动器窗口（本地完成，待发行）

设置页新增独立的“启动器窗口”：macOS/Windows 可选择融合或系统原生标题栏，保存后在下次正常创建窗口时生效，不强制重启；已知位置的环境可记忆普通外框/最大化并按 DIP 工作区纠正离屏位置。Linux 保持原生标题栏，默认保守分支仅记最大化，不猜测后台或伪造坐标；显式 X11 的几何能力另验。恢复摆放只作用于 Lua，游戏窗口和草稿保持独立。完整1102项（新增46项）与构建通过；界面9项原创注入另记。生产Electron源码bundle真实窗口/文件7组检查通过，普通大小/最大化、关闭再激活换样式、记忆开关和恢复均验证，3源/state不变，920px五容器无溢出。窗口操作由BrowserWindow脚本API触发，非真实按钮/拖动/双击/多屏；3次Java枚举返回空替身、3次vm_stat尝试被阻止，未执行真实Java/子进程/网络/游戏。挂起关闭与最大化中间矩形两实际P2已修复；独立84项（46新增受管+10原创探针+28不重叠旧相关）通过，有限范围无未修阻塞；未签名macARM包版本/架构/hash与ASAR八文件、ZIP内ASAR/Mach-O/DMG尾标核验通过，包未执行。本提交三平台CI/公开资产、实际系统按钮/多屏矩阵另验。界面缩放拆至0.15.1。详见窗口用法与边界。公开下载仍为0.10.2。

0.15.1 有限界面缩放（本地完成，待发行）

窗口设置新增由主进程能力表控制的缩放，90/100/110/125仅开放macOS原生标题栏的内容缩放与已验布局，其他平台/模式保持100并保留已保存目标与原因。显示实际/目标比例和未知读回，恢复100在坏配置下也可尝试恢复当前显示而不覆盖未知文件。schema1不自动迁移，明确非100后schema2，旧0.15读取新格式会保留并提示。普通DIP窗口记忆不随CSS缩放改变；没有强制重启、CSS整页变形或放大最小外框。UI12项注入与标签修复后1项定向分记；忙碌漂移/窄窗导航名称两实际P2已修复复验。完整1130项、独立103项与最终构建通过，主JS555.71kB/gzip166.97kB的默认提示保留；生产源码bundle原生6组/三尺寸四档12组合实测，3源/state不变，Java枚举3空替身/vm_stat3尝试阻止，实际子进程/网络/Java/game为0。原生key/menu是脚本，wheel/drift是合成/注入，不当OS键盘/鼠标/pinch或Win/Linux证据。未签名macARM包版本/架构/hash、ZIP-ASAR/DMG尾标与8文件核验通过，包未执行；当前提交三平台CI/公开发行和实际OS输入另验。详见缩放说明。公开下载仍为0.10.2。

0.16.0 本地实例库（待发行）

“我的实例”增加列表/网格、标准/紧凑、四类升降排序及24项分页；已有搜索扩展到1–3个实例，并可匹配版本、加载器和整合包名称。排序只使用本机登记，“本机最近启动记录”不代表进入世界；未知时间置后。筛选、排序和翻页不改变启动目标，隐藏的当前实例有定位入口；设置草稿继续按实例保留。显示枚举仅保存在桌面/浏览器各自的本地偏好，不写实例或世界。

完整1153/1153（新增23项）、独立59/59和构建通过；最终UI注入11组/16布局与独立焦点1组/3守卫分记，刷新移走焦点行的实际P2已修。生产Electron真实main/preload/Core/renderer/本地存储和原创FS验9组/12个125%布局，初始化后52项源/state不变；文件夹端口为明确替身，非Finder实测。没有认证、Java、游戏、网络或实例写入。未签名macARM版本/架构/hash、ZIP-ASAR、DMG尾标和八文件核同，包未执行；当前提交三平台CI/公开资产另验。见实例库用法、开发和审核。

0.17.0 本地全局设置搜索（待发行）

设置页新增18项已有全局设置的静态检索。输入只更新结果，点击才一次定位原控件或说明行；不改变手动/自定义模式、草稿，不执行保存、Java检测/下载、更新或窗口恢复。搜索词最多100码点、仅会话内保留，无新存储或后端schema；实例设置搜索/分类/实验页未做。

完整1180/1180（新增27项）、独立66/66（27新受管+7原创纯探针+28旧相关+3搜索DOM组+1计时器DOM组，即62Node/4DOM）与构建通过。最终UI注入12组/4布局和5条虚拟计时器守卫分记；生产Electron实际main/preload/Core/renderer/本地存储/原创FS验8组、1240/920/880DIP×两主题的6个125%布局，12个搜索/关闭计时阶段均零新增IPC与存储写入。初始化后4源/state文件不变；首次设置的Java/内存/要求三读取回调各1次为替身，明确切B后内存/要求各再1次，非真实Java。0网络/子进程/外部打开/文件选择/实例写入/pageerror。未签名macARM版本/架构/hash/ZIP-ASAR/DMG尾标及八文件核同，包未执行；当前提交CI/公开资产与OS输入/屏幕阅读器/WinLinux/游戏另验。 两项有限P3已修：纯helper的继承上下文读取，以及旧自动检查开关未取消尚未开始的启动计时器；不将它们称为搜索引发的联网或App安全漏洞。见设置搜索、开发和审核。

0.17.1 本地实例设置搜索（待发行）

当前实例页新增8项已有设置和2项恢复操作的独立检索，显式高级结果可展开原高级区域，始终只定位来源控件/动作行，不修改继承、潜伏草稿或执行恢复。按真实ID卸载后查询与高级展开重置，App原有逐实例草稿保留；保存错误焦点优先，A/B/迟到意图隔离，无新后端或搜索存储。

完整1204/1204（新增24项）、独立85/85（24新受管+3原创纯探针+55旧相关+3DOM组，即82Node/3DOM）和构建通过。最终UI注入11组/4个125%布局另记；生产Electron实际main/preload/Core/renderer/本地存储及原创FS验7组/10目标、三尺寸两主题6个125%布局与11个零新增IPC/存储写入阶段。初始化后4源/state完整hash与身份不变；显式A/B的生产instanceOptions读取共5次，配置的Java/内存/要求/更新替身均0调用，0网络/子进程尝试/外部打开/picker/实例写入/pageerror。未签名macARM版本/架构/hash/ZIP-ASAR/DMG尾标及8文件核同，包未执行；本提交CI/公开资产及OS键盘/屏幕阅读器/WinLinux/游戏另验。 本轮有限审核未发现产品P1/P2/P3；脚本更正单独留痕，分类/实验与更广运行配置仍待。见实例搜索、开发和审核。