BMCLAPI 启动器下载接口文档（整理版）

> 整理时间：2026-10-20（UTC+8）
> 根地址：`https://bmclapi2.bangbang93.com`（官方文档中个别示例也写作 `https://bmclapi.bangbang93.com`）
>
> 来源说明
> - 【官方文档】= https://bmclapidoc.bangbang93.com/ （apidoc 生成的页面，内容取自其 `assets/main.bundle.js`，生成时间 2026-05-14）
> - 【HMCL 源码】= https://github.com/HMCL-dev/HMCL/blob/main/HMCL/src/main/java/org/jackhuang/hmcl/download/HMCLDownloadProvider.java
> - 【实测】= 2026-10-20 16:15（UTC+8）用 curl 实测的结果（只取小文件 / 前 200 字节 / 看重定向）
>
> 官方文档没写到的内容，标为“未找到”。

---

0. 使用规范（【官方文档】“协议”一节）

- BMCLAPI 下的所有文件，除 BMCLAPI 本身的源码之外，归源站点所有。
- BMCLAPI 会尽量保证文件的完整性、有效性和实时性；使用 BMCLAPI 带来的一切纠纷与 BMCLAPI 无关。
- BMCLAPI 不开源（和 BMCL 不同）。
- 所有使用 BMCLAPI 的程序，必须在下载界面或其他可见位置标明来源。
- 禁止在 BMCLAPI 上二次封装其他协议。
- 意见反馈：https://www.bangbang93.com/category/6/bmclapi ；开发者通知 TG 频道：https://t.me/bmclapi
- 文档给的参考实现：BMCL 的 Mirror 实现 https://github.com/bangbang93/BMCL/tree/master/BMCLV2/Mirrors

限速 / User-Agent 要求：官方文档中未找到。
【实测】`/java/list` 用默认 curl UA 和浏览器 UA 访问都返回 `403 Forbidden`（`server: WAFPRO`），原因不明。其他接口用 curl 默认 UA 都能正常访问。
【实测】大文件（manifest、libraries、assets、java-runtime 等）会先 302 到 OpenBMCLAPI 节点（如 `https://xxx.sakura.sld.tw/download/<hash>?name=..&s=..&e=..`）或 `mirrors.cernet.edu.cn/bmclapi/...`，所以客户端必须跟随重定向。

---

1. 官方域名 → BMCLAPI 替换对照表

来源：【官方文档】“使用”一节（目标是 100% 兼容官方目录结构，只是根路径不同）；另列【HMCL 源码】里的规则作交叉验证。
注意【实测】：通过 BMCLAPI 拿到的版本 JSON，里面的 URL 仍然是官方域名（如 `https://piston-meta.mojang.com/...`、`https://piston-data.mojang.com/...`、`https://libraries.minecraft.net/...`），启动器要自己按上表替换。

---

2. 下载一个原版版本的完整流程

2.1 版本列表

- `GET /mc/game/version_manifest.json`
- `GET /mc/game/version_manifest_v2.json`
- 示例：https://bmclapi2.bangbang93.com/mc/game/version_manifest_v2.json
- 来源：【官方文档】替换表。【实测】302 到 OpenBMCLAPI 节点，可用。

2.2 版本 JSON

方式一（推荐，官方结构）：把 manifest 里 `versions[].url` 的域名换成 BMCLAPI。
方式二（BMCLAPI 专用接口）：

`GET /version/:version/:category` —— 【官方文档】“下载mc本体文件”（Version 组）
- 返回 302 到真实地址（文档示例：`Location: /mc/game/1.7.10/server/952438ac.../server.jar`）。
- 示例：
- https://bmclapi2.bangbang93.com/version/1.20.1/json → 【实测】302 到 `/v1/packages/a5cf661d.../1.20.1.json`
- https://bmclapi2.bangbang93.com/version/1.20.1/client → 【实测】302 到 `/v1/objects/0c3ec587.../client.jar`
- https://bmclapi2.bangbang93.com/version/1.20.1/server → 【实测】302 到 `/v1/objects/84194a2f.../server.jar`

2.3 client / server jar

- 版本 JSON 里 `downloads.client.url` / `downloads.server.url`，把 `https://piston-data.mojang.com`（或旧的 `https://launcher.mojang.com`）换成 `https://bmclapi2.bangbang93.com`。
- 示例：`https://bmclapi2.bangbang93.com/v1/objects/0c3ec587af28e5a785c0b4a7b8a30f9a8f78f838/client.jar`
- 或直接用 2.2 的 `/version/:version/client|server`。

2.4 Libraries

- 版本 JSON 里 `libraries[].downloads.artifact.url` / `classifiers`，把 `https://libraries.minecraft.net/` 换成 `https://bmclapi2.bangbang93.com/maven/`（官方文档）或 `.../libraries/`（HMCL 用法）。
- 示例：`https://bmclapi2.bangbang93.com/maven/com/mojang/brigadier/1.1.8/brigadier-1.1.8.pom` 【实测】302 可用；`/libraries/...` 同样可用。

2.5 Assets 索引

- 版本 JSON 的 `assetIndex.url`，域名换成 BMCLAPI。
- 示例（1.20.1）：`https://bmclapi2.bangbang93.com/v1/packages/50ce48459eb9e29836662862273d7b15d41c2c33/5.json` 【实测】可用。

2.6 Assets 对象

- `GET /assets/<hash前2位>/<hash>`（对应 `https://resources.download.minecraft.net/<hash前2位>/<hash>`）
- 来源：【官方文档】替换表；【HMCL 源码】`bmclRoot + "/assets/" + assetObject.getLocation()`。
- 【实测】从 1.20.1 索引里取一个真实 hash 测试，HEAD 返回 200。

2.7 Java 运行时

1. Mojang Java 运行时清单（【官方文档】替换表）：
`https://bmclapi2.bangbang93.com/v1/products/java-runtime/2ec0cc96c44e5a76b9c8b7c39df7210883d12871/all.json` 【实测】302 可用。
清单里各文件的 URL 怎么替换（`piston-data` 等），官方文档没写，按 piston-data → 根地址的通用规则推断，未实测。
2. `GET /java/list` —— 【官方文档】“获取java列表”（Java 组，v2.3.0）
- 描述：可视作 https://java.com/zh_CN/download/manual.jsp 的序列化结果，缓存 Windows / macOS / Linux 的 JRE 安装包（不缓存 Solaris）；只保留最新 JRE，同步最长延迟 24 小时；返回的文件名可直接下载，例如 `https://bmclapi.bangbang93.com/java/jre_x64.exe`。
- 返回：数组，元素字段 `title`（名称）、`file`（文件名）。
- 【实测】当前返回 403 Forbidden（WAF），可能已停用或被拦截。

---

3. Forge（【官方文档】Forge 组，源 `forge/forge.controller.ts`）

build 对象字段：`branch`、`build`、`mcversion`、`modified`、`version`、`files[]`（`format`、`category`、`hash`(md5)）。`category` 常见值：`installer`、`universal`、`mdk`、`userdev`、`changelog`、`installer-win`、`src`、`javadoc`。

下载地址拼接规则（文档原文）：

示例：
- https://bmclapi2.bangbang93.com/forge/minecraft/1.20.1 【实测 200】
- https://bmclapi2.bangbang93.com/forge/download?mcversion=1.20.1&version=47.3.0&category=installer&format=jar 【实测】302 → `/maven/net/minecraftforge/forge/1.20.1-47.3.0/forge-1.20.1-47.3.0-installer.jar`
- https://bmclapi2.bangbang93.com/forge/download/1847 【实测】302 → `.../1.8.9-11.15.1.1847/forge-1.8.9-11.15.1.1847-installer.jar`（未指定 category 时默认给 installer，这是实测现象，文档没写）

---

4. NeoForge（【官方文档】Neoforge 组）

Maven 直链见第 1 节替换表。
示例：
- https://bmclapi2.bangbang93.com/neoforge/list/1.21.1 【实测 200】
- https://bmclapi2.bangbang93.com/neoforge/version/21.1.200/download/installer.jar 【实测】302 → `/maven/net/neoforged/neoforge/21.1.200/neoforge-21.1.200-installer.jar`
- https://bmclapi2.bangbang93.com/neoforge/meta/api/maven/details/releases/net/neoforged/neoforge 【实测 200】

---

5. Fabric

官方文档没有专门接口，只给了替换规则：`meta.fabricmc.net` → `/fabric-meta`，`maven.fabricmc.net` → `/maven`。路径沿用 Fabric 官方 meta API。
- `GET /fabric-meta/v2/versions/loader` 【实测 200】（HMCL 源码也用这个）
- `GET /fabric-meta/v2/versions/game` 【实测 200】（HMCL 源码也用这个）
- 其他 Fabric meta 路径（如 `/v2/versions/loader/:game/:loader/profile/json`）：按替换规则应可用，未在文档中列出，未实测。

6. Quilt

官方文档：`meta.quiltmc.org` → `/quilt-meta`，`maven.quiltmc.org/repository/release` → `/maven`，并注明“由于上游 API 存在 bug，暂时不可用”。
【实测】`https://bmclapi2.bangbang93.com/quilt-meta/v3/versions/loader` 当前返回 200，但文档仍标为不可用，生产使用请谨慎。HMCL 源码里没有 Quilt 的 BMCLAPI 规则。

7. LiteLoader（【官方文档】Liteloader 组）

也可以手工拼接：`/maven/com/mumfrey/liteloader/${mcversion}/liteloader-${version}.jar`；SNAPSHOT 版用 `/maven/com/mumfrey/liteloader/${version}/liteloader-${version}.jar`。
示例：https://bmclapi2.bangbang93.com/liteloader/download?version=1.12.2-SNAPSHOT 【实测】302 → `/maven/com/mumfrey/liteloader/1.12.2-SNAPSHOT/liteloader-1.12.2-SNAPSHOT.jar`

8. OptiFine（【官方文档】Optifine 组）

手工拼接：`/maven/com/optifine/${mcversion}/Optifine_${mcversion}_${type}_${patch}.jar`，但 1.12 起文件名规则变了，文档推荐用 API。
示例：https://bmclapi2.bangbang93.com/optifine/1.12.2/HD_U/G5 【实测】302 → `/maven/com/optifine/1.12.2/OptiFine_1.12.2_HD_U_G5.jar`

9. 其他

- `GET /mirrors/authlib-injector` —— 同步自 https://github.com/yushijinhun/authlib-injector.yushi.moe ，路径与原站一致（如 `/mirrors/authlib-injector/artifacts.json`，【实测】可用）。
- `GET /openbmclapi/sponsor` —— 随机返回一个赞助商 `{_id, link, name}`，可以用来在启动器里展示来源 / 赞助。【实测 200】

10. 未找到的内容

- 限速策略、并发限制、User-Agent 要求：官方文档里都没有。
- Java 运行时清单中各文件的替换规则：官方文档没写。
- Fabric / Quilt 的完整接口列表：官方只给了域名替换规则。
- Cleanroom、Modrinth、CurseForge：不属于 BMCLAPI（HMCL 用的是其他镜像，如 `mod.mcimirror.top`）。