文档 / 使用指南源码核对 · 2026.11.17 · 507e3b7
GUIDE

使用指南

账户设置、版本安装、实例管理和资源下载的操作说明,按当前源码流程整理。

本指南介绍 OneLauncher 的安装、账户、游戏版本、实例和资源管理,依据仓库界面与核心代码编写,核对至 2026-11-17 / 507e3b7。发布包的可用平台、服务地址与部分界面可能随版本调整;下方截图来自项目仓库,实际界面以下载版本为准。

下载与安装

OneLauncher 是面向 Minecraft Java 版的桌面启动器,不是 Minecraft 游戏本体,也不会替代游戏授权。首次使用建议准备拥有 Java 版游戏权益的 Microsoft 账户、可用的网络,以及能容纳游戏、资源和存档的磁盘空间。

选择适合你的发布包

  1. 打开 OneLauncher 发布页,阅读版本说明。
  2. 选择与你的操作系统和 CPU 架构相符的产物。桌面项目面向 Windows、Linux 与 macOS,但具体提供哪些下载包,以该次发布实际列出的文件为准。
  3. 根据包的形式解压或运行。压缩包应完整解压,不要只取出其中一个程序文件,也不要在压缩软件的临时目录里长期运行启动器。
  4. 将启动器放在你有读写权限的目录。首次运行需要创建配置、账户和游戏数据目录;权限不足时,应先解决目标目录的访问问题。

不同发布形式的运行要求不同:Native AOT、自包含与依赖框架的 JIT 包,不应一概按同一种 .NET Runtime 要求处理。如果发布说明要求额外运行时,按说明安装;从源码构建则需要 .NET 10 SDK,详见开发文档。如果发布页暂时没有你的平台或架构对应的包,请查看源码构建说明,而不是下载一个名称相近但架构不同的文件。

截至 2026 年 11 月 17 日,最新发布 v1.6.1.0 列出 Windows OneLauncher.Desktop.exe,没有 Linux/macOS 二进制附件。其他平台可以使用源码构建说明;GitHub 自动生成的源码 ZIP / tar.gz 不是可直接运行的发布包。

关于旧安装命令:仓库已迁移到 lnetface/OneLauncher。README 中仍有指向旧 zhweaa 地址的一键安装命令,而当前源码快照里已经没有对应的 OneLauncher.Desktop/install.ps1。本指南不提供该旧命令,建议从新仓库发布页获取文件。

Windows 上的 Microsoft WAM 系统登录和 MCT 联机助手是平台特定能力;Linux、macOS 上的 Microsoft 登录使用系统浏览器。跨平台桌面支持并不意味着这些 Windows 能力在所有系统上都有相同实现。

首次启动

打开应用后,左侧导航包含“开始菜单”“版本管理”“游戏数据”“服务器收藏”“下载管理”“资源检索”“账户管理”和“设置选项”。建议按以下顺序开始,不必先研究所有高级参数。

  1. 添加账户:进入“账户管理”,添加自己的 Microsoft 账户,并将它设为默认账户。这样后续创建实例时会关联到正确身份。
  2. 选择游戏版本:进入“下载管理”,等待版本列表加载,选中你想玩的 Minecraft 版本。
  3. 选择玩法环境:只玩原版时不要勾选加载器;需要模组时选择该模组要求的 Fabric、Quilt、NeoForge 或 Forge(预览)。
  4. 准备 Java:如果没有为该游戏版本准备 Java,请勾选“自动安装匹配的 Java 运行环境”。这个选项不是默认开启的,首次安装尤其应确认。
  5. 开始下载:点击“下载版本”,等待元数据、主文件、库、资源、加载器及校验阶段完成。可在“开始菜单”中的“任务中心”点击“进入”查看进度与取消任务。
  6. 启动游戏:成功后启动器会登记实例并设为默认启动项。在开始菜单选择它,点击“快速游戏”;也可以在“游戏数据”列表中点击该实例的“启动”。

首次初始化会创建一个本机 default 用户,因此应用能进入下载界面并不代表已经完成正版登录。建议在开始玩之前设置自己的账户,尤其是需要连接在线验证服务器时。

基础版本安装完成后,推荐模组可能作为另一个任务继续执行。请区分“版本已经安装”和“推荐模组也全部安装成功”;在任务中心检查各自状态,再开始需要这些模组的游戏。

添加和管理账户

Microsoft 正版账户

进入“账户管理”→添加账户,在“登录方式”中选择“微软账户”,点击“登录 Microsoft 账户”。Windows 默认使用系统 Web Account Manager;希望用浏览器,或系统登录遇到兼容性问题时,可勾选 “使用浏览器登录”。Linux 和 macOS 走系统浏览器认证流程。

登录不只验证 Microsoft 用户名:启动器还会依次完成 Xbox Live、XSTS、Minecraft Services 登录、游戏权益与玩家档案检查。你的账户需要拥有相应 Minecraft 游戏权益,并完成 Minecraft 玩家名称等档案设置。仅有 Microsoft 账户但没有游戏权益,不会自动获得 Java 版授权。

仓库截图:Microsoft 账户登录界面

成功后回到账户列表,将常用用户设为默认。列表支持刷新账户和移除用户,但至少需要保留一个有效用户模型。为不同实例指定账户时,可以选择一个具体用户,也可以选择“全局默认账户”;选择全局默认后,启动时会读取当时的默认用户,而不是永远固定为创建实例时的某个用户。

离线账户与外置登入

“离线账户”只保存在本机,不进行在线身份验证。输入游戏用户名后点击“添加账户”;当前规则只接受英文字母、数字和下划线。离线身份不能替代正版服务器要求的身份认证,也不是取得游戏授权的方式。

“外置登入”填写用户名或邮箱及密码,再点击“登录”。当前桌面入口实际调用 LittleSkin,没有可填写任意验证服务器地址的输入框;核心包含 Yggdrasil 能力,不等于当前 UI 已开放所有外置服务器。

新增离线和外置账户受 DefaultSettings.AllowNonMicrosoftLogin 配置控制。默认模型允许,但桌面启动时同步的资源清单可能改变该值;如果提示禁用非微软账户,请按当前配置使用 Microsoft 登录。这个检查针对新增账户,不会自动删除此前保存的用户。

保护账户数据:不要公开上传整个 playerdata 目录或 MSAL 缓存。某些缺少 libsecret/DBus 的 Linux 环境会回退到本地未加密缓存,更应限制数据目录的访问权限。提交问题时只提供经过检查的错误文本,不要附密码、Cookie 或令牌。

实现依据:账户界面与登录分支

安装 Minecraft 与模组加载器

“下载管理”中的游戏版本和“游戏数据”中的实例是两层概念。下载页安装共享版本与加载器,随后创建可启动的实例;同一个版本可以供多个实例使用。

阅读安装选项

选项 什么时候使用
不勾选加载器 安装原版环境
Fabric 模组明确要求 Fabric 时;可同时安装 Fabric API
Quilt 模组或整合包明确要求 Quilt 时;可同时安装 QSL
NeoForge 使用适配 NeoForge 的模组;Beta 版本需要显式允许
Forge(预览) 模组要求 Forge 时;可优先选择推荐版,但仍属预览支持
自动安装匹配的 Java 运行环境 尚未准备该版本所需 Java 时
一键安装推荐模组 已选加载器,并希望安装兼容的推荐资源与依赖时

仓库截图:Minecraft 下载与安装选项

当前 UI 的最低版本门槛是:Fabric、Quilt 从 1.14 开始;NeoForge 从 1.20.2 开始;Forge 从 1.2 开始。这是入口限制,不是所有具体 Minecraft/加载器组合都经过验证的承诺。实际能否安装还取决于上游元数据、版本文件与加载器支持情况。遇到整合包要求的精确加载器版本时,请优先使用包的导入流程。

同时勾选多个加载器,会分别创建独立实例,不会把它们混装进同一个实例。 当前创建顺序为 Fabric、Forge、NeoForge、Quilt,首个实例设为该版本的默认项。普通用户只需选择实际玩法需要的一个加载器。

下载进度、失败与取消

下载侧栏会显示当前阶段、文件名与文件进度,最终成功登记实例后才显示完成。取消按钮会通知同一个后台任务停止;需要等待任务退出,不要在取消过程中手动删除正在使用的目录。

单个游戏文件的所有下载源失败时,“重试”只重新下载那个文件,其他文件仍可继续;“忽略”会结束此次安装,不是忽略缺失文件后继续把安装判定为成功。失败后先核对网络、镜像和错误中的目标文件,再重试。

实现依据:安装、失败重试及实例登记

Java 与游戏内存

Minecraft 的不同版本可能需要不同 Java,大版本选择不应凭“越新越好”。安装页的“自动安装匹配的 Java 运行环境”会优先读取 Minecraft 元数据里的 Java 要求,缺省时才按游戏版本回退判断;不是所有游戏版本都使用 Java 21。自动下载提供商是 Adoptium。

手动安装 Java

  1. 打开“设置选项”,选择“运行环境”。
  2. 点击“安装 Java”。
  3. 在侧栏选择 Java 大版本和提供商,点击“安装”。
  4. 等待任务完成。已登记的大版本会显示“覆盖安装”,只有确实需要替换时才使用。

默认可选版本包括 8、11、16、17、21、24、25,列表来自配置,后续可能改变。提供商包括 Adoptium、Azul Zulu、Microsoft OpenJDK、GraalVM 和 Oracle JDK;并不保证每个提供商都为每个大版本和平台发布文件。

覆盖安装会替换该大版本的运行时目录。已有的其他实例若依赖它,也可能受到影响。启动器可以读取已配置运行时,也会尝试已有托管目录或系统 PATH,但 PATH 中找到的 Java 不一定符合目标游戏版本要求。出现“系统未安装 Java”或不兼容错误时,请先确认真实可执行文件和大版本,而不是反复切换加载器。

JVM 优化模式

“设置选项”→“游戏启动”提供保守、标准与激进模式。它们按可用内存、Java 位数、模组数量等信息估算预算,是启发式配置,不是帧率或性能提升的保证。多数使用者可以从标准模式开始,旧设备或排查兼容问题时尝试保守模式。

主动切换模式会整份替换默认 JVM 预设,包括此前手动修改的字段。 已经调整高级参数的用户,应先备份配置。可用内存不足、堆参数冲突或不合法的手工值会被报告为错误;给游戏分配超过实际可用内存的数值并不能让它更稳定。

管理独立游戏实例

“版本管理”展示已安装版本和加载器;“游戏数据”管理独立的游戏环境。原版、Fabric 模组实例和不同整合包可以拥有各自名称、账户、模组、存档与配置,同时复用基础版本。

新建与启动

  1. 打开“游戏数据”,点击“新建实例”。
  2. 选择已经安装的基础版本。
  3. 从该版本已经安装的加载器能力中选择一个,填写实例名称。
  4. 选择固定账户或全局默认账户,按需要勾选推荐模组,再保存。
  5. 在实例列表点击“启动”。也可把常用实例“设为默认”,回到开始菜单快速启动。

新建侧栏只能选择基础版本已经安装的加载器。如果列表没有需要的类型,请回到下载管理安装。给原版实例改名不会安装 Fabric。

仓库截图:游戏数据与实例编辑

整理和备份

使用标签过滤区分生存、模组和测试实例;排序可按版本或创建时间进行。进入“编辑”可改名、指定默认用户、选择标签、更换图标、打开实例文件夹、创建桌面快捷启动、复制实例以及打包为整合包。快捷启动的具体文件形式依平台而异。

“复制此实例”复制实例内容并登记新实例,适合在大幅更改模组前保留一个副本。“打包该实例为整合包”会生成 .mrpack,存放在实例根目录,实例文件放入包的 overrides。分享前检查存档、截图、服务器列表、配置和已有压缩包;导出并不提供全面的隐私清理,也不替你审核各模组的再分发许可。

“移除此游戏数据”会删除实例记录和实例目录,无法撤销。有价值的世界请先备份 saves,并按需保存 mods、config、资源包与截图。基础版本共享目录与实例目录并非同一个文件夹,备份时应确认打开的是哪个目录。

实现依据:实例编辑、复制、导出和删除

安装模组、光影和整合包

“资源检索”连接 Modrinth。当前页面提供 模组、光影包、整合包三种类型;输入关键词搜索,点击结果打开安装侧栏。当前没有在线资源包搜索入口,资源包可按 Minecraft 的通常方式放入目标实例的 resourcepacks,再在游戏里启用。

仓库截图:Modrinth 资源检索

模组

选中模组后选择目标游戏实例,确认 Minecraft 版本与加载器匹配,再安装。侧栏默认包含依赖选项,通常建议保留;启动器会解析需要下载的依赖。若提示不支持当前版本或加载器,请改选兼容实例或资源,而不是把文件强行塞进另一个环境。

版本匹配并不保证所有模组组合都没有冲突。大批量添加前复制实例,先安装少量资源并测试;游戏退出时关注日志里的依赖缺失、冲突和加载器错误。

光影包

选择光影包和目标实例后,文件会安装到该实例的 shaderpacks。下载光影文件不等于光影环境已准备好:当前安装服务不会检查或安装 Iris、OptiFine 等依赖,也不会自动在游戏里启用该光影。你需要准备与游戏和加载器兼容的渲染环境,再在 Minecraft 的光影设置中选择文件。

整合包与推荐模组

整合包侧栏先加载包信息,显示名称、Minecraft 和加载器。点击安装会创建一个新实例,完成后到“游戏数据”查看,不会把包直接覆盖到随意选择的旧实例。失败或取消后可重新获取包重试;可选图标下载失败不会把已经成功登记的实例改成可重复安装的失败项。

推荐模组可在版本下载、新建实例时勾选,也可在实例编辑中点击“一键安装推荐模组”。仅支持 Fabric、Quilt、Forge 和 NeoForge 实例,按版本与加载器筛选兼容资源与依赖。推荐安装是独立任务,取消它会保留已经建立的基础实例;请在任务中心确认最后结果。

实现依据:资源类型与搜索侧栏 · 实现依据:光影文件安装边界

导入已有游戏与整合包

从 PCL2 导入

  1. 在“开始菜单”找到“导入游戏实例”,选择“从 PCL2 导入...”。
  2. 选择 PCL2 的单个版本实例文件夹,例如 .minecraft/versions/1.21.1-Fabric…,不要选 PCL2 程序,也不要选整个 .minecraft。
  3. 确认文件夹里有 PCL/Setup.ini 和版本 JSON;不满足检查时会显示“这不是有效的PCL版本文件夹”。
  4. 等待分析版本、规划文件、复制可复用文件、补全安装和复制实例内容。
  5. 完成后到“游戏数据”检查导入实例的名称、版本、加载器和账户,再启动。

导入会优先复制本地共享文件,并按标准安装流程联网补全缺失内容、处理加载器及校验,所以并非保证完全离线。原 PCL2 文件是复制来源,不是被移动后删除;仍建议导入前自行备份存档。不要在导入尚未结束时清理源文件或目标目录。

从 .mrpack 导入

在“导入游戏实例”选择“从整合包 (.mrpack) 导入...”,选择 Modrinth .mrpack 文件。导入器读取其中的 modrinth.index.json、Minecraft 与加载器依赖及文件清单,创建新实例。保留网络连接,等待任务完成后到游戏数据查看。

桌面选择器只接受 .mrpack,不是任意普通 ZIP 或其他启动器私有整合包格式。若你拿到的 ZIP 只是包含一个 .mrpack,可先提取内部包再通过桌面导入;高级控制台导入能力见开发文档。若用独立控制台登记了新实例,已打开的桌面应用可能需要重新加载列表或重启才能看到。

实现依据:PCL2 版本识别、复制与安装

服务器收藏与朋友联机

收藏一个服务器

进入“服务器收藏”添加收藏,填写服务器地址、端口、名称和可选描述,并选择一个本地已存在的游戏实例。默认端口是 25565,允许范围为 1 到 65535。保存后启动器可以读取服务器信息、同步到关联实例的游戏服务器列表;在收藏卡片上启动时,会用该关联实例加入服务器。

服务器收藏不是自动安装整合包的入口。客户端的 Minecraft 版本、加载器及模组仍需要与服务端兼容。如果原实例被删除,收藏会失去启动目标;编辑收藏并关联到仍然存在的合适实例即可。

Windows MCT 联机助手

在“开始菜单”找到“联机面板”并点击“进入”。联机核心是 Windows 的 MCT main.exe,初次初始化需要下载与校验;受网络和核心资源地址可用性影响。不应在校验失败时绕过检查。

房主操作:

  1. 选择“创建房间”,选择要启动的游戏实例。
  2. 点击“创建房间并启动游戏”。
  3. 进入自己的世界,在 Minecraft 中开放局域网,并记下游戏显示的端口。
  4. 复制房间码,将房间码和该游戏端口一起发给朋友。房间码不能替代端口。

加入者操作:

  1. 提前安装与房主兼容的版本、加载器及模组,并把正确实例设为该版本默认项。
  2. 选择“加入房间”,粘贴房间码,填写房主开放局域网的游戏端口。
  3. 点击“加入房间并启动游戏”,等待 P2P 连接建立。界面会显示本地服务器地址,连接通过本地转发进行。
  4. 结束后点击“断开连接”。

当前房间码包含节点和 Minecraft 版本,但不全面验证双方模组内容一致,也不自动下载房主整合包。没有正确版本默认实例时存在回退选择,因此双方提前准备一致环境非常重要。兼容 MCT 的 M…C 房间码只启动 P2P 服务,不自动启动 Minecraft;这时自行启动兼容实例并使用显示的本地地址连接。

实现依据:创建房间、加入分支与 MCT 兼容模式

调整界面、下载和数据路径

“设置选项”支持“全部设置”“界面”“游戏启动”“下载”“运行环境”分类过滤。找不到某项时先切回全部设置,不必重置整个配置。

主页设置

界面设置提供默认与“魔法按钮”两种主页样式、主页默认启动项、背景图片、主页板块与左导航显示控制。主页默认启动项可以是游戏实例,也可以是服务器收藏。部分主页板块显示设置只在魔法按钮样式生效;主页与设置导航始终保留,隐藏其他页面不会删除对应游戏或账户数据。

下载策略

默认下载与 SHA-1 校验并发均为 24,开启 SHA-1,使用“官方源”。可以选择“BMCLAPI源竞速”“OLON源竞速”或“SkyCrystal源竞速”:每一种都让官方源与选中的一个镜像同时尝试,不是默认同时使用全部镜像。网络不稳定时适当降低下载并发,或选择可用镜像。

建议保持 SHA-1 校验开启。校验是完整性检查,关闭它不等于解决下载损坏,也不能把失败文件变为可用文件。镜像、模组服务和登录服务是不同链路,切换游戏镜像不一定能解决 Microsoft 或 Modrinth 连接问题。

安装路径与备份

默认数据目录在用户主目录的 OneLauncher,默认安装目录在其中的 installed。共享游戏数据位于 installed/minecraft,各实例位于 installed/minecraft/instance/<实例 ID>;配置是数据目录里的 config.json,账户位于 playerdata/account.json。

运行环境的“游戏安装路径”可选择基本路径、运行路径或自定义。自定义模式可用“选择路径”,或输入后点击“应用”。应使用有读写权限、空间足够的目录。

更换路径不会自动复制、移动或删除原有游戏数据。 保存后会提醒退出,新的路径在重启启动器后生效。先备份,再自行迁移必要数据,并检查重启后显示的“当前生效路径”;不要把旧实例暂时看不见误判为文件已经被启动器删除。

遇到问题时

先记录错误窗口中的具体阶段和目标文件,区分安装失败、账户认证失败与游戏本身退出。以下是常见检查顺序。

现象 建议先检查
下载或元数据失败 网络、目标版本、当前镜像;适当降低并发,按提示重试失败文件
Java 未安装或不兼容 游戏需要的大版本、实际可执行文件、Java 配置或 PATH;必要时重新安装匹配版本
Microsoft / XSTS 登录失败 游戏权益、Xbox 档案、家庭或年龄许可、服务可用性;Windows 尝试浏览器登录
提示“请选择一个启动项” 是否已经创建实例,开始菜单是否选中,主页默认启动项是否存在
模组不支持加载器或版本 目标实例环境与 Modrinth 文件要求是否一致;不要混用 Forge 与 Fabric 文件
光影下载后不出现效果 是否已有兼容渲染模组,是否在游戏内启用,是否安装到正确实例
服务器收藏无法启动 收藏关联的实例是否还存在,版本与模组是否和服务端兼容
改路径后看不到旧实例 当前生效路径与原目录,是否完成重启和自行迁移
MCT 核心校验失败 网络与上游核心资源更新;保留错误,不绕过校验

游戏启动后退出,可在“游戏数据”的启动下拉中选择“调试模式启动”,查看游戏输出。也检查实例自己的 logs 和启动器数据目录中的 logs。启动器错误日志按会话保存,首条错误出现后才创建文件,所以没有错误时看不到会话日志是正常现象。日志写入也可能因权限或磁盘问题失败,不应把“没有日志”理解为“没有错误”。

提交问题报告

到 GitHub Issues 提供:OneLauncher 发布版本、操作系统和架构、Minecraft 版本、Java 大版本、加载器与主要模组、可重复的操作步骤、预期结果、实际结果,以及检查后的错误文本或日志片段。尽量从一个可复现的最小实例开始,说明问题发生在版本下载、推荐模组、登录、启动还是联机阶段。

不要提交整个账户数据目录。日志和启动参数也可能包含敏感身份信息;检查并移除密码、令牌、私人服务器信息和不必要的本机路径后再上传。不要为排错直接删除唯一存档、全部配置或账户缓存;先复制备份,再进行有明确目的的局部检查。

本指南依据固定源码快照编写,未在你的机器上验证游戏运行。项目历史测试记录不代表本次验证结果;新版本的操作以实际界面与发布说明为准。