bloomery
v1.8.0
Published
Minecraft 启动器
Readme
Bloomery 启动器
Minecraft 启动器命令行。TypeScript 编写，Node ≥ 20，零运行时依赖。
安装
npm i -g bloomery
bloomery --version从源码：
git clone https://github.com/EtherosGroup/Bloomery.git
cd Bloomery
npm install
npm run start -- --version更新
npm i -g bloomery@latest快速开始
bloomery folder add ~/.minecraft # 登记游戏文件夹
bloomery java scan # 扫描本机 Java
bloomery auth login cibocaz # 离线账户
bloomery install 1.20.6 # 安装原版
bloomery install 1.20.6 --loader fabric # 安装加载器版本
bloomery launch # 启动install 的输出末行给出该实例的启动命令，直接复制即可。
命令
bloomery [全局选项] <命令> [命令选项] [参数]launch
启动游戏。省略版本时按序取：当前选中 → 上次启动 → 第一个可用。
bloomery launch # 启动默认实例
bloomery launch 1.20.6-fabric-0.19.5 # 指定实例 id
bloomery launch --dry-run # 只打印启动计划
bloomery launch --account cibocaz # 指定账户
bloomery launch --folder mc # 指定文件夹启动当前选中实例时，首行给出提示。
install
安装指定版本。目录名默认按版本与加载器推导。
bloomery install 1.20.6 # 原版
bloomery install 1.20.6 --loader fabric # 最新 fabric
bloomery install 1.20.6 --loader [email protected] # 指定加载器版本
bloomery install 1.20.6 --loader quilt
bloomery install 1.20.6 --loader forge # 官方安装器，取最新正式版
bloomery install 1.20.6 --loader [email protected] # 指定 Forge 版本，游戏版本前缀可省
bloomery install 1.20.6 --loader neoforge # neoforge 版本号不带游戏版本前缀
bloomery install 1.20.6 --loader [email protected]
bloomery install 1.20.6 --name MyPack # 指定实例名
bloomery install 1.20.6 --no-assets # 跳过资源对象同名实例已存在时拒绝，不覆盖。
auth
账户管理。离线账户立即可用，微软账户见下文。
bloomery auth login cibocaz # 离线账户
bloomery auth login --type microsoft # 微软设备码登录
bloomery auth list
bloomery auth logout cibocazmod
从 Modrinth 检索与安装 MOD。
bloomery mod search sodium # 检索
bloomery mod search sodium --limit 20
bloomery mod install sodium # 装进实例的 mods/
bloomery mod install sodium --version 1.20.6-fabric
bloomery mod install sodium-extra --deps # 连必需依赖
bloomery mod install sodium --no-deps
bloomery mod install sodium --dry-run # 只算不装目标实例省略时同 launch 的规则。文件落在该实例自己的 mods/ 下，同名文件已存在时跳过。目前只接 Modrinth。
modpack
导入 Modrinth 的 .mrpack。
bloomery modpack pack.mrpack
bloomery modpack pack.mrpack --name MyPack # 实例名
bloomery modpack pack.mrpack --dry-run # 只算不导入
bloomery modpack pack.mrpack --no-assets按包里的游戏版本与加载器建实例，随后下清单文件（校验 sha1）、摊平 overrides/ 与 client-overrides/。清单里没有下载地址的文件只记警告，不中止。
view
加载器与游戏版本互相查询。
bloomery view loader # 四种加载器概览
bloomery view loader fabric # 某加载器的全部版本，每页 20 条
bloomery view loader fabric --page 2
bloomery view loader neoforge --type release # 只看正式版
bloomery view loader fabric --game 1.20.6 # 该游戏版本上可用的加载器版本
bloomery view loader fabric --games # 该加载器支持的游戏版本
bloomery view game 1.20.6 # 该游戏版本上四种加载器各有哪些版本发布通道由版本号判断：含 alpha 为预览，含 beta / rc / pre / snapshot 为测试，其余为正式。
version
bloomery version list # 列出实例，标出当前选中
bloomery version info 1.20.6-fabric-0.19.5 # 单个实例详情
bloomery version select 1.20.6-fabric-0.19.5 # 选中选中后 launch 与 mod install 省略版本时都用它。优先级：命令行给的 > 当前选中 > 上次启动 > 第一个可用。
folder
bloomery folder add ~/.minecraft # 登记
bloomery folder list
bloomery folder scan ~/.minecraft # 扫描磁盘上已有版本
bloomery folder select mc # 切换当前文件夹
bloomery folder remove mcjava
bloomery java scan # 扫描
bloomery java list
bloomery java add /usr/lib/jvm/jdk-21/bin/java
bloomery java which 1.20.6 # 该版本会用哪个 Java
bloomery java remove /path/to/java
bloomery java list --major 21mirror
查看、切换下载源，或从镜像站拉取清单。默认 Mojang 官方直连。
bloomery mirror list # 预置源、拉来的源与当前选择
bloomery mirror use bmclapi # 切到 BMCLAPI
bloomery mirror use official # 切回官方
bloomery mirror use custom --url https://mirror.example.com
bloomery mirror update --from https://example.com/mirrors.json
bloomery mirror update # 不给 --from 就用上次的地址update 拉取的清单格式（数组，或 { "entries": [...] }）：
[{ "name": "bmclapi", "label": "BMCLAPI", "base": "https://bmclapi2.bangbang93.com" }]拉来的清单缓存在 <配置目录>/mirrors.json（含来源地址与拉取时刻），mirror use <名字> 对预置与拉来的源一视同仁；拉来的源按 custom 写入。BMCLAPI 只改写 Mojang 主机（库、资源、版本 json），Forge 等第三方 maven 原样直连。写入的是 setting.json 的 download.sources。
全局选项
-v, --verbose 输出调试日志
-q, --quiet 只输出警告与错误
--json 以 JSON 输出结果
--progress <style> 进度输出：bar / plain / off / ndjson
-h, --help 显示帮助
-V, --version 显示版本号全局选项写在命令名之前：bloomery --json install 1.20.6。
--json 下标准输出只有一份 JSON，过程提示静默。
--json 出错时标准输出给一份机器可读的错误（人类可读的那份仍写 stderr）：
{
"error": {
"code": "DownloadFailed",
"message": "下载失败",
"detail": "forge 安装器",
"exit": 1,
"context": { "url": "…" }
}
}code 是稳定的错误码，message 是它对应的中文短语，exit 是进程退出码。
--progress ndjson 把进度写成机器可读事件到 stderr（标准输出不受影响），供外壳读取：
{ "v": 1, "stage": "库", "done": 12, "total": 47, "bytes": true }节流 100ms 一条；新阶段与收尾必发；stderr 积压超过 64KB 时丢中间帧（收尾那条仍强制写），因此消费端再慢也不会拖慢下载。
加载器
| 加载器 | 安装方式 | 版本号写法 |
| -------- | ---------- | ----------------------------------------- |
| fabric | 官方 meta | [email protected] |
| quilt | 官方 meta | [email protected] |
| neoforge | 官方安装器 | [email protected] |
| forge | 官方安装器 | [email protected] 或 [email protected] |
版本号与游戏版本必须配对：
- neoforge 的版本号前两段即所需游戏版本（
20.6.x对应 1.20.6，21.1.x对应 1.21.1） - forge 的版本号以游戏版本为前缀，省略前缀时自动补
- 配对不符时直接报错，不下载安装器
省略加载器版本时取该游戏版本上最新的正式版。
forge 与 neoforge 走官方安装器：下载安装器到 <文件夹>/.bloomery/，执行完删除；过程需要本机 Java，耗时数分钟，输出实时透传。--name 指定实例名时，安装器写出的版本目录整份改名接管，继承链只留一层。
存储
按 PCL / HMCL 的布局存放，只使用版本隔离模式：
<游戏文件夹>/
versions/<实例 id>/
<实例 id>.json # 版本描述
<实例 id>.jar # 客户端 jar
mods/ # MOD
config/ # 配置
natives/ # 解出的本地库
libraries/ # 共享库
assets/ # 共享资源MOD、配置、存档都在实例目录下，互不影响。
配置与日志：
~/.config/bloomery/
setting.json # 文件夹、账户、下载源、代理、并发、选中项
state.json # 上次启动的实例、Java 探测缓存
logs/latest.log下载源、代理与并发在 setting.json 的 network 段（concurrency 默认 8，四类文件按任务数分配）。
微软登录
内置应用 id 已通过 Mojang 审核，直接登录：
bloomery auth login --type microsoft流程为设备码：终端给出一串代码与网址（https://www.microsoft.com/link），浏览器完成授权。凭据过期时启动前自动刷新。--client-id <id> 或环境变量 BLOOMERY_CLIENT_ID 可覆盖内置值。
开发
npm run start -- <参数> # 直接跑源码，Node 原生剥离类型
npm run check # tsc --noEmit
npm test # node --test，167 项
npm run fmt # oxfmt 格式化
npm run build # 产物到 dist/分层：cli → 功能模块 → platform / infra / output。系统分支只出现在 src/platform/。
发版：npm version <版本> --no-git-tag-version → 提交 → 打 v<版本> 标签 → 推送。标签触发 npm 发布与 Release 打包。
许可
见 LICENSE。