创云镜像 · API 文档

用户端 在线调试 芯创云
目录
基础约定站点统计核心与图标 核心分类 版本与构建下载与断点续传 Java 专区 错误码完整示例

基础约定

项目说明
Base URLhttps://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"
}
上为 2026-09-18 线上实测值。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}
  ]
}

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", …} ]
}

GET/api/v1/types?category={id} 可选的分类过滤

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"}
      ]
    }, ...
  ]
}

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 编码)。

首段是磁盘上的核心目录名,不是显示名(2026-09-19 本地实例实测): 显示名是 Legacy Fabric(带空格,出现在 JSON 的 name 里), 而 /dl 首段与 files[].url、302 的 Location 一律是磁盘目录名 Legacy-Fabric。用显示名请求直链(/dl/Legacy%20Fabric/…)会 404, 必须使用列表接口给出的 url,不要自己用 name 拼路径。
# 断点续传
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"}
     ]}
  ]
}
字段说明
okfalse 只表示加载失败(从未成功编目过);true 不代表一定有文件
enabledok:true + enabled:false = 未启用(正常空响应)
stale / stale_agestale_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[].sha25664 位小写十六进制,或 null(未知)
files[].verified是否已由本站算出可信哈希;verified:true 绝不伴随空/短哈希
files[].hash_source"proxy"(本站代理首次完整下载时算出并缓存)或 "pending"(尚未计算)
files[].url本站相对路径(/java/dl/jdk-<大版本>/<平台>/<文件名>),可直接拼接本站域名下载
关于 SHA-256 的诚实说明:本站的 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-{大版本}/{平台}/{文件名} 流式代理下载

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未收录于编目(不转发/不触上游)/核心未启用/哈希尚未计算/路径形状不合法
416Range 不可满足(附 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 专区未收录或哈希尚未计算;隐藏段/越界路径)
416Range 参数无效(附 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
提示:Minecraft 核心数据同步自 mcjars.app 与各核心官方发布源,每 2 小时自动增量更新; Java 专区数据来自自建 OpenList。下载量大时请合理使用断点续传,避免重复流量。 Java 文件的 SHA-256 需经本站代理完整下载一次后才可用(见上文说明)。