CPTProgrammer/ModReleaser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
ModReleaser/docs/modrinth/get-meta.md
CPTProgrammer 346b0783d8
Add documentation for Mod Releaser project
2026-07-06 04:56:50 +08:00

7.2 KiB
Raw Permalink Blame History

Modrinth 元数据查询 API 使用文档

本文档描述如何获取 Modrinth 平台支持的所有加载器（loaders） 和 Minecraft 游戏版本（game versions），以及项目类型、分类等元数据。这些接口均为公开接口，无需认证。

基本信息

项目 内容
生产环境 https://api.modrinth.com/v2
认证 无需认证（全部公开）
Rate Limit 每 IP 每分钟 300 请求

接口一：获取所有加载器

获取 Modrinth 支持的全部模组加载器列表。

项目 内容
端点 GET /tag/loader
认证 否
成功响应码 200
响应体 LoaderTag[] — 加载器对象数组

响应字段（LoaderTag）

字段 类型 说明 示例
name string 加载器名称 "fabric"
icon string 加载器的 SVG 图标 "<svg>...</svg>"
supported_project_types string[] 该加载器适用的项目类型 ["mod", "modpack"]

请求示例

curl "https://api.modrinth.com/v2/tag/loader"

const response = await fetch("https://api.modrinth.com/v2/tag/loader");
const loaders = await response.json();

for (const loader of loaders) {
  console.log(`${loader.name} — 适用于: ${loader.supported_project_types.join(", ")}`);
}

响应示例

[
  {
    "icon": "<svg>...</svg>",
    "name": "fabric",
    "supported_project_types": ["mod", "modpack"]
  },
  {
    "icon": "<svg>...</svg>",
    "name": "forge",
    "supported_project_types": ["mod", "modpack"]
  },
  {
    "icon": "<svg>...</svg>",
    "name": "quilt",
    "supported_project_types": ["mod", "modpack"]
  },
  {
    "icon": "<svg>...</svg>",
    "name": "neoforge",
    "supported_project_types": ["mod", "modpack"]
  },
  {
    "icon": "<svg>...</svg>",
    "name": "minecraft",
    "supported_project_types": ["resourcepack", "shader"]
  }
]

注意： "minecraft" 加载器用于资源包（resourcepacks）、光影等不需要模组加载器的项目类型。

接口二：获取所有游戏版本

获取 Modrinth 支持的全部 Minecraft 版本列表，包含版本类型和发布日期。

项目 内容
端点 GET /tag/game_version
认证 否
成功响应码 200
响应体 GameVersionTag[] — 游戏版本对象数组

响应字段（GameVersionTag）

字段 类型 说明 示例
version string 游戏版本号 "1.18.1"
version_type string 版本类型：release、snapshot、alpha、beta "release"
date string 版本发布日期（ISO-8601） "2021-12-10T00:00:00Z"
major boolean 是否为主要版本，用于 Featured Versions 标记 true

请求示例

curl "https://api.modrinth.com/v2/tag/game_version"

const response = await fetch("https://api.modrinth.com/v2/tag/game_version");
const versions = await response.json();

// 仅列出正式发布版
for (const v of versions.filter(v => v.version_type === "release")) {
  console.log(`${v.version} (${v.version_type})${v.major ? " [主要版本]" : ""}`);
}

响应示例

[
  {
    "version": "1.21.4",
    "version_type": "release",
    "date": "2025-04-04T00:00:00Z",
    "major": true
  },
  {
    "version": "1.21.3",
    "version_type": "release",
    "date": "2024-11-02T00:00:00Z",
    "major": false
  },
  {
    "version": "1.20.1",
    "version_type": "release",
    "date": "2023-06-12T00:00:00Z",
    "major": true
  },
  {
    "version": "24w45a",
    "version_type": "snapshot",
    "date": "2024-11-06T00:00:00Z",
    "major": false
  }
]

辅助接口：项目类型

获取 Modrinth 支持的项目类型，用于了解加载器适用哪些类型的项目。

项目 内容
端点 GET /tag/project_type
响应体 string[] 
curl "https://api.modrinth.com/v2/tag/project_type"

["mod", "modpack", "resourcepack", "shader"]

辅助接口：分类标签

获取 Modrinth 的项目分类列表（含图标和适用项目类型）。

项目 内容
端点 GET /tag/category
响应体 CategoryTag[] 
curl "https://api.modrinth.com/v2/tag/category"

响应字段：

字段 类型 说明
icon string 分类的 SVG 图标
name string 分类名称
project_type string 该分类适用的项目类型
header string 该分类所属的标题分组

常见使用场景

场景 1：构建上传表单的下拉选项

在发布模组的 UI 中，动态获取可选加载器和游戏版本：

const [loaders, gameVersions] = await Promise.all([
  fetch("https://api.modrinth.com/v2/tag/loader").then(r => r.json()),
  fetch("https://api.modrinth.com/v2/tag/game_version").then(r => r.json())
]);

// 加载器下拉
const loaderNames = loaders.map(l => l.name);
// → ["fabric", "forge", "quilt", "neoforge", "minecraft", ...]

// 仅正式版游戏版本
const releaseVersions = gameVersions
  .filter(v => v.version_type === "release")
  .map(v => v.version);
// → ["1.21.4", "1.21.3", "1.20.4", ...]

场景 2：验证用户输入是否合法

在上传版本前，校验 loaders 和 game_versions 中填的值是否被 Modrinth 接受：

const validLoaders = new Set(loaders.map(l => l.name));
const validVersions = new Set(gameVersions.map(v => v.version));

const invalidLoaders = userInputLoaders.filter(l => !validLoaders.has(l));
const invalidVersions = userInputVersions.filter(v => !validVersions.has(v));

if (invalidLoaders.length > 0 || invalidVersions.length > 0) {
  console.error("不合法的值:", { invalidLoaders, invalidVersions });
}

场景 3：获取某个加载器支持的 project_type

用于判断某个加载器是否适用于 mod、modpack 等类型：

const loaders = await fetch("https://api.modrinth.com/v2/tag/loader").then(r => r.json());

const fabricInfo = loaders.find(l => l.name === "fabric");
console.log(fabricInfo.supported_project_types); // → ["mod", "modpack"]

// 判断 fabric 是否支持 mod 类型
const supportsMod = fabricInfo.supported_project_types.includes("mod"); // → true

缓存建议

这些元数据接口的返回值在短期内不会频繁变化，强烈建议在客户端做缓存：

  • 加载器列表：以天为单位缓存（加载器新增频率极低）。
  • 游戏版本列表：以小时或天为单位缓存（仅在 Minecraft 新版本发布时需要刷新）。
// 简单的内存缓存示例
let cachedLoaders = null;
let cacheTime = 0;
const CACHE_TTL = 86400000; // 24 小时

async function getLoaders() {
  if (cachedLoaders && Date.now() - cacheTime < CACHE_TTL) {
    return cachedLoaders;
  }
  cachedLoaders = await fetch("https://api.modrinth.com/v2/tag/loader").then(r => r.json());
  cacheTime = Date.now();
  return cachedLoaders;
}

参考