基础约定
| 项目 | 说明 |
|---|---|
| Base URL | https://www.coremirrors.com |
| 数据格式 | 全部接口返回 application/json; charset=utf-8(图标与文件下载除外) |
| 核心标识 | {type} 可用类型键(PAPER)或显示名(Paper),大小写不敏感 |
| 路径编码 | 游戏版本/构建/文件名需 URL 编码(如 #232 → %23232) |
| 排序 | 游戏版本与构建版本均按自然排序、新→旧返回 |
| 分页 | 构建列表支持 limit(每页条数,≤200)与 offset(偏移)参数,响应含 count 总数 |
| 缓存 | 列表类接口约 30 秒服务端缓存,新下载完成的构建最长 30 秒后可见;API 的 JSON 响应一律 Cache-Control: no-store |
| 时间格式 | ISO 8601;last_sync/server_time 形如 2026-09-18T02:05:31+0800,构建的 created 为上游原样的 UTC(…Z,如 2025-06-09T12:18:55.778Z) |
| 鉴权 | 本页全部公开接口无需认证(无 Cookie / Token 要求);面板(后台)内部接口不属于公开 API,不在本页范围内 |
GET/api/v1/stats 站点统计
curl https://www.coremirrors.com/api/v1/stats
{
"size_bytes": 2003261091688, "size_human": "1.8 TB",
"builds": 214807, // 本地已镜像构建数
"site_builds": 220357, // 上游站点构建总数
"types": 31, // 核心类型数
"last_sync": "2026-09-18T02:05:31+0800"
}
types 为核心类型总数 31:
它来自 scan_type_registry() 扫描磁盘 <output_dir>/<X>-ICON/info.json
(与 /api/v1/types 的 count 同源),与官方发布源注册表(30 项)不是算术叠加;
官方基岩版核心 BEDROCK 同时是磁盘上的真实目录(自己的 info.json 与本地构建,
公开 API 可见),并仍保留在 VIRTUAL_TYPES 里作兜底(上游 API 不可用时面板/sitemap 不丢它)。
线上磁盘上这 31 个 -ICON 目录恰好等于注册表 30 项 + BEDROCK,属观测事实而非代码机制。
last_sync 的实际格式是 YYYY-MM-DDTHH:MM:SS+0800。last_sync 也可能是 null(2026-09-19 线上实测):
服务刚启动、或尚未成功完成过一轮同步时它是 null。除
size_bytes/size_human/builds/site_builds/types
之外的字段不要假设恒为非空。builds 是本地已镜像构建数,site_builds 是上游站点构建总数,
两者由不同来源统计,不要求相等。category 是派生字段(core_category_of()),取值为
插件 / 模组 / 混合 / 基岩 / 其他,
category_en 为对应的 Plugins / Mods / Hybrid /
Bedrock / Other。「基岩」覆盖基岩生态核心 BEDROCK(官方 BDS)、
ENDSTONE、LEVILAMINA;上游 categories 数组
(official / plugins / modded …)原样透传,不因本分类而改写。
线上实测各类计数(2026-09-19):插件 15、模组 6、混合 4、基岩 3、其他 3。GET/api/v1/types 核心列表
全部核心类型(31 种,含 YOUER/MAGMA/DIVINEMC 等),每个核心带中英文简介。
curl https://www.coremirrors.com/api/v1/types
{
"base": "https://www.coremirrors.com",
"count": 31,
"types": [
{
"type": "PAPER", "name": "Paper",
"homepage": "https://papermc.io/software/paper",
"categories": ["plugins"],
"category": "插件",
"category_en": "Plugins",
"description": "基于 Spigot 的高性能插件服务端,大幅优化性能并扩展大量 API,插件服首选。",
"description_en": "High performance Spigot fork with a rich API.",
"deprecated": false, "experimental": false,
"site_builds": 5660, "local_builds": 4321,
"icon": "https://www.coremirrors.com/dl/Paper-ICON/icon.png",
"versions_url": "https://www.coremirrors.com/api/v1/types/PAPER/versions"
}, ...
]
}
type 是 API 键(PAPER),name 是显示名(Paper),
两者都可能与磁盘目录名不同(如显示名 Legacy Fabric 对应磁盘目录
Legacy-Fabric,见「下载与断点续传」)。description 是本站中文简介
(无映射时回退上游英文简介),description_en 是英文简介。site_builds / local_builds
允许为 null 或 0(2026-09-19 线上实测:BEDROCK 的
site_builds 为 null、local_builds 为 389)。base 取后台配置的 public_base_url,未配置时为 null。
GET/api/v1/types/{type} 核心详情
单个核心的信息(含简介),结构与上面 types[] 一致。未知核心 →
404 {"error": "未知核心类型: XXX"}。
GET/api/v1/types/{type}/icon 核心图标
curl -O https://www.coremirrors.com/api/v1/types/Paper/icon # 302 -> /dl/Paper-ICON/icon.png
302 跳转到图标直链,带 Cache-Control: public, max-age=86400;磁盘上没有图标文件时回退上游图标
URL,两者都没有 → 404 {"error": "图标不存在"}(icon 字段同样遵循这套回退,可能为空串;
图标扩展名不固定,线上实测有 icon.png 与 icon.webp)。
核心分类
分类口径与 /api/v1/types 的 category 字段完全一致(同一个
core_category_of() 派生),不引入任何额外存储;两个接口都是公开只读。
GET/api/v1/categories 分类列表
curl https://www.coremirrors.com/api/v1/categories
{
"count": 5,
"categories": [
{"id": "插件", "name": "插件", "name_en": "Plugins", "count": 15},
{"id": "模组", "name": "模组", "name_en": "Mods", "count": 6},
{"id": "混合", "name": "混合", "name_en": "Hybrid", "count": 4},
{"id": "基岩", "name": "基岩版", "name_en": "Bedrock", "count": 3},
{"id": "其他", "name": "其他", "name_en": "Other", "count": 3}
]
}
id就是/api/v1/types[].category的取值(中文 id);name_en与category_en同口径name是中文展示名:只有「基岩」的展示名与 id 不同(基岩→基岩版), 其余回退成 id 本身count是该分类下的核心(类型)数量;全部count之和恒等于/api/v1/types的count(实测相等)- 只列出当前确实有核心的分类(
count > 0),不输出空分类 - 顺序固定:
插件 → 模组 → 混合 → 基岩 → 其他;将来出现的新分类排在末尾 (按中文 id 排序,顺序稳定)
GET/api/v1/categories/{id} 该分类下的核心列表
{id} 是宽松匹配、大小写不敏感的:中文 id(基岩)、
中文展示名(基岩版)、英文名(Bedrock / bedrock /
BEDROCK)都能命中;URL 编码(%E5%9F%BA%E5%B2%A9)与未编码的 UTF-8 字节都支持。
curl "https://www.coremirrors.com/api/v1/categories/%E5%9F%BA%E5%B2%A9"
curl "https://www.coremirrors.com/api/v1/categories/Bedrock"
{
"id": "基岩", "name": "基岩版", "name_en": "Bedrock", "count": 3,
"types": [ {"type": "BEDROCK", "name": "Bedrock", "category": "基岩", "category_en": "Bedrock", …} ]
}
types[]与/api/v1/types里的条目逐字段同形 (复用同一个type_summary(),不是精简结构)- 未知分类 →
404 {"error": "未知分类: <传入值>"}(文案风格与「未知核心类型: X」一致) - 已知分类但当前 0 个核心 →
200+count: 0+types: [](与 404 明确区分:404 只表示「这个分类 id 不存在」)
GET/api/v1/types?category={id} 可选的分类过滤
- 不传
category→ 与原来完全一致(全量 31 项,响应逐字节不变) - 传入 → 与
/api/v1/categories/{id}同一套宽松匹配;count/types是过滤后的结果(base字段仍在) - 未知分类值 →
404 {"error": "未知分类: <传入值>"},不是空列表: 空列表无法区分「分类不存在」与「分类存在但没核心」,后者按上面的约定是200
curl "https://www.coremirrors.com/api/v1/types?category=%E5%9F%BA%E5%B2%A9" # 基岩 3 项
curl "https://www.coremirrors.com/api/v1/types?category=bedrock" # 同上(大小写不敏感)
版本与构建(游戏版本 / 构建版本分开)
GET/api/v1/types/{type}/versions 游戏版本列表
curl https://www.coremirrors.com/api/v1/types/Paper/versions
{
"type": "PAPER", "name": "Paper", "count": 66,
"game_versions": ["26.2", "26.1.2", "26.1.1", "…", "1.8.8"]
}
{type} 只接受核心键(如 PAPER、LEGACY_FABRIC)
或注册表里的精确显示名(如 Paper、Legacy Fabric,空格需 URL 编码)。
用 sanitize() 后的磁盘目录名(如 Legacy-Fabric)请求会返回 404——
这是既有语义,不是故障。GET/api/v1/types/{type}/versions/{game} 构建版本列表
某游戏版本下的构建版本,每个构建含下载直链与 SHA-256。支持分页参数 limit/offset。
curl "https://www.coremirrors.com/api/v1/types/Paper/versions/1.21.4?limit=10&offset=0"
{
"type": "PAPER", "name": "Paper", "game_version": "1.21.4",
"count": 224, "limit": 10, "offset": 0,
"builds": [
{
"build": "#232", "folder": "#232",
"uuid": "e60f6fa0-ae4d-480b-b4dd-56af5afd48bf",
"project_version": null, "created": "2025-06-09T12:18:55.778Z",
"experimental": false, "changes": ["Fix infinite loop in RegionFile IO"],
"files": [
{"file": "paper-1.21.4-232.jar", "size": 51437498,
"sha256": "5ee4f542f628a14c644410b08c94ea42e772ef4d29fe92973636b6813d4eaffc",
"kind": "",
"url": "https://www.coremirrors.com/dl/Paper/1.21.4/%23232/paper-1.21.4-232.jar"}
]
}, ...
]
}
limit默认0= 全部;服务端强制上限200(超过按 200 处理)。offset默认0- 二者必须是整数,否则
400 {"error": "limit/offset 需为整数"}; 未知游戏版本 →404 {"error": "未知游戏版本: X"}(limit造成的空页不算 404) count是该游戏版本下的构建总数,与limit/offset无关files[].kind字段存在但可能为空串(2026-09-19 线上 Paper 构建实测"kind": ""), 不要把它当作非空分类使用
GET/api/v1/types/{type}/versions/{game}/{build} 单个构建详情
结构同 builds[](外加 type/name/game_version)。{build} 可用构建名或目录名。
未知构建 → 404 {"error": "未知构建: X"}。
GET/api/v1/download 下载跳转(302)
| 参数 | 必填 | 说明 |
|---|---|---|
type | 是 | 核心键或名称 |
game | 是 | 游戏版本 |
build | 是 | 构建版本(如 #232) |
file | 是 | 文件名 |
curl -L "https://www.coremirrors.com/api/v1/download?type=Paper&game=1.21.4&build=%23232&file=paper-1.21.4-232.jar" -o paper.jar
命中 → 302 + Location: <本站>/dl/<核心磁盘目录名>/<游戏版本目录>/<构建目录>/<文件名>,
该 Location 与列表接口的 files[].url 逐段一致(同一棵树、同一套目录名)。
参数缺失/核心未知 → 400 {"error": "参数缺失: type/game/build/file 必填"};
文件不在该构建里 → 404 {"error": "文件不存在"}。
文件下载与断点续传
下载直链格式:/dl/{核心目录名}/{游戏版本目录}/{构建目录}/{文件名}(各段 URL 编码)。
Legacy Fabric(带空格,出现在 JSON 的 name 里),
而 /dl 首段与 files[].url、302 的 Location 一律是磁盘目录名
Legacy-Fabric。用显示名请求直链(/dl/Legacy%20Fabric/…)会 404,
必须使用列表接口给出的 url,不要自己用 name 拼路径。- 支持
Range(HTTP 206),断点续传:curl -C - -O URL- 响应带
Content-Range: bytes a-b/total与Accept-Ranges: bytes - 不可满足的 Range(起点 ≥ 文件大小、start > end、语法非法)→
416+Content-Range: bytes */<size> - 后缀范围
Range: bytes=-N(最后 N 字节)同样支持
- 响应带
.jar/.zip/.gz自动带下载头(Content-Disposition: attachment; filename="…"; filename*=UTF-8''…, 文件名过滤 CRLF/控制字符/引号);其他扩展名 →inline(不带文件名参数)- 每个文件同目录有
<文件名>.sha256文本文件(64 位十六进制 + 换行),供完整性校验; 该旁文件不存在时 →404 - 隐藏段(请求路径任一段以
.开头,或realpath解析后落到隐藏目录/越界软链) 一律404:/dl/.cache/java_hashes.json、/dl/../../etc/passwd都是 404 - 直链响应带
Cache-Control: public, max-age=31536000, immutable(同 URL 内容不可变)
# 断点续传
curl -C - -o paper.jar "https://www.coremirrors.com/dl/Paper/1.21.4/%23232/paper-1.21.4-232.jar"
# SHA-256 校验
curl -s "https://www.coremirrors.com/dl/Paper/1.21.4/%23232/paper-1.21.4-232.jar.sha256"
sha256sum paper.jar
Java 专区(JDK 镜像)
数据来自自建 OpenList 实例(只读)。编目由后端定时拉取并落盘快照,浏览器不直连 OpenList;
下载一律经过本站流式代理。该功能由 config.json 的 openlist 段控制,默认关闭。
GET/api/java/list JDK 编目(公开)
curl https://www.coremirrors.com/api/java/list
{
"ok": true, // false 只表示"加载失败"(从未成功编目)
"enabled": true, // false = 未启用(正常空响应, 不是错误)
"stale": false, // 快照是否可能过期
"stale_age": 13, // 快照年龄(秒), = now - updated
"root": "/JAVA-JDK", // 远端根目录名(契约值, 不含主机名)
"updated": 1789672135, // 快照时间: epoch 秒(不是毫秒/不是字符串)
"total_files": 62,
"total_size": 10369181533, // 字节
"platforms": ["linux-x64", "linux-aarch64", "mac-x64", "mac-aarch64", "windows-x64", "windows-aarch64"],
"majors": [ // 按大版本升序; major 是字符串
{"major": "8", "label": "JDK 8", "latest_version": "8u492-b09", "file_count": 5,
"files": [
{"name": "OpenJDK8U-jdk_x64_windows_hotspot_8u492b09.msi",
"platform": "windows-x64", "os": "windows", "arch": "x64",
"format": "msi", "kind": "jdk", "vendor": "Temurin",
"version": "8u492-b09", "size": 88866816, "modified": "2026-07-19T20:26:40Z",
"sha256": null, "verified": false, "hash_source": "pending",
"url": "/java/dl/jdk-8/windows-x64/OpenJDK8U-jdk_x64_windows_hotspot_8u492b09.msi"}
]}
]
}
| 字段 | 说明 |
|---|---|
ok | false 只表示加载失败(从未成功编目过);true 不代表一定有文件 |
enabled | ok:true + enabled:false = 未启用(正常空响应) |
stale / stale_age | stale_age 为快照年龄(秒);超过 TTL 或快照被截断 → stale:true |
updated | 快照时间,epoch 秒(int) |
total_files / total_size | 文件总数与总字节数;total_files 恒等于全部 majors[].files 之和 |
platforms | 出现过的平台,顺序固定,数组顺序即展示顺序 |
majors | 按大版本号升序(实测 8,11,17,18,20,21,22,24,25,26);major 是字符串,latest_version 为该大版本最新版本 |
files[].sha256 | 64 位小写十六进制,或 null(未知) |
files[].verified | 是否已由本站算出可信哈希;verified:true 绝不伴随空/短哈希 |
files[].hash_source | "proxy"(本站代理首次完整下载时算出并缓存)或 "pending"(尚未计算) |
files[].url | 本站相对路径(/java/dl/jdk-<大版本>/<平台>/<文件名>),可直接拼接本站域名下载 |
sha256 是代理首次对该文件完整
下载时边下载边计算、然后缓存的。因此没有经过本站完整下载的文件没有 sha256——接口返回
"sha256": null + "verified": false + "hash_source": "pending",
页面上显示为「未校验(下载后可校验)」。Range 请求(部分下载)不会产生哈希,
也绝不返回空值或伪造值。线上实测(2026-09-19):62 个文件里 61 个 pending、1 个 proxy。openlist.public_expose=false 时,未认证请求 /api/java/list →
401 {"error": "未登录"}(不下发任何编目数据);面板登录后的请求仍可看到完整编目。GET/java/dl/jdk-{大版本}/{平台}/{文件名} 流式代理下载
- 只接受编目里真实存在的成员;未收录路径直接
404,且不触上游 - 不带
Range→ 完整下载(200),边转发边算 SHA-256 并写入缓存 Range: bytes=0-0→206+Content-Range: bytes 0-0/88866816- Range 越界 →
416+Content-Range: bytes */<size> - 上游忽略
Range回200时,本站自行切片,仍回 206(不静默降级为整文件) - 成功响应带
Accept-Ranges: bytes与Cache-Control: public, max-age=31536000, immutable,并透传上游的Content-Type/Etag/Last-Modified - 路径形状校验:主版本段形如
jdk-17、平台段只允许[A-Za-z0-9][A-Za-z0-9._-]*、文件名不得含/\NUL 或换行且 ≤255 字符; 不合法 →404(纯文本说明),且不触上游
GET{上面的 url}.sha256 哈希文本
已算出 → 200,正文为 64 位十六进制(text/plain; charset=utf-8,
Cache-Control: public, max-age=300);尚未下载过(哈希未知)→ 404
(正文 SHA-256 尚未计算: 该文件还没有完成过一次完整下载);未收录于编目 → 404;
proxy_enabled=false 时与下载一并 503。
# 断点续传 + 校验
curl -C - -O https://www.coremirrors.com/java/dl/jdk-21/linux-x64/OpenJDK21U-jdk_x64_linux_hotspot_21.0.11_10.tar.gz
sha256sum OpenJDK21U-jdk_x64_linux_hotspot_21.0.11_10.tar.gz
# 已算出 -> 200(线上实测)
curl -s https://www.coremirrors.com/java/dl/jdk-26/windows-x64/OpenJDK26U-jdk_x64_windows_hotspot_26.0.1_8.msi.sha256
# 尚未计算 -> 404
curl -s https://www.coremirrors.com/java/dl/jdk-8/linux-x64/OpenJDK8U-jdk_x64_linux_hotspot_8u492b09.tar.gz.sha256
Java 专区状态码
| 状态码 | 含义 |
|---|---|
401 | 仅当 openlist.public_expose=false 且未登录 |
404 | 未收录于编目(不转发/不触上游)/核心未启用/哈希尚未计算/路径形状不合法 |
416 | Range 不可满足(附 Content-Range: bytes */size;取不到真实大小时为 bytes */*) |
502 | 上游返回非 404 的异常状态,或非超时类连接失败 |
503 | 编目尚未就绪/本站 Java 代理被关闭(proxy_enabled=false)/断路器打开(上游不可达后约 30 秒冷却,正文含「约 N 秒后重试」) |
504 | 上游响应超时 |
错误正文是纯文本说明,绝不回显上游地址、token 或 sign=。编目里的
url 一律是本站相对路径,内网 OpenList 地址从不下发。
错误码
| 状态码 | 含义 |
|---|---|
200 | 成功(JSON / .sha256 文本) |
206 | 部分内容(Range 请求) |
302 | 跳转到下载直链(/api/v1/download)或图标直链 |
400 | 参数缺失/校验失败(如 /api/v1/download 缺 type/game/build/file;limit/offset 非整数) |
401 | 仅当 openlist.public_expose=false 时的 /api/java/list |
404 | 资源不存在(未知核心/版本/构建/文件;Java 专区未收录或哈希尚未计算;隐藏段/越界路径) |
416 | Range 参数无效(附 Content-Range: bytes */size) |
500 | 服务器内部错误 |
502 / 503 / 504 | 仅 Java 专区代理:上游异常 / 未就绪或代理关闭或断路器冷却 / 上游超时 |
完整示例
BASE=https://www.coremirrors.com
# 1. 站点统计
curl $BASE/api/v1/stats
# 2. 核心列表(含中英文简介与分类)
curl $BASE/api/v1/types
# 2b. 按分类浏览: 分类列表 + 某分类下的核心
curl $BASE/api/v1/categories
curl "$BASE/api/v1/categories/%E5%9F%BA%E5%B2%A9" # 基岩(也可写 Bedrock)
curl "$BASE/api/v1/types?category=bedrock" # 等价过滤写法
# 3. Paper 的游戏版本
curl $BASE/api/v1/types/Paper/versions
# 4. 1.21.4 的构建版本(分页: 每批 10 个)
curl "$BASE/api/v1/types/Paper/versions/1.21.4?limit=10&offset=0"
# 5. 单个构建
curl $BASE/api/v1/types/Paper/versions/1.21.4/%23232
# 6. 直链下载(断点续传)
curl -C - -o paper.jar $BASE/dl/Paper/1.21.4/%23232/paper-1.21.4-232.jar
# 7. Java 专区编目(JDK 8–26 全平台)
curl $BASE/api/java/list
# 8. Java 断点续传 + 校验
curl -C - -O $BASE/java/dl/jdk-21/linux-x64/OpenJDK21U-jdk_x64_linux_hotspot_21.0.11_10.tar.gz
curl -s $BASE/java/dl/jdk-21/linux-x64/OpenJDK21U-jdk_x64_linux_hotspot_21.0.11_10.tar.gz.sha256