# 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"]` |

### 请求示例

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

```js
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(", ")}`);
}
```

### 响应示例

```json
[
  {
    "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` |

### 请求示例

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

```js
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 ? " [主要版本]" : ""}`);
}
```

### 响应示例

```json
[
  {
    "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[]` |

```bash
curl "https://api.modrinth.com/v2/tag/project_type"
```

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

---

## 辅助接口：分类标签

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

| 项目 | 内容 |
|------|------|
| **端点** | `GET /tag/category` |
| **响应体** | `CategoryTag[]` |

```bash
curl "https://api.modrinth.com/v2/tag/category"
```

响应字段：

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

---

## 常见使用场景

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

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

```js
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 接受：

```js
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 等类型：

```js
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 新版本发布时需要刷新）。

```js
// 简单的内存缓存示例
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;
}
```

---

## 参考

- [Modrinth API 文档](https://docs.modrinth.com)
- [OpenAPI 规范文件](openapi.yml)
- [获取版本信息 API](get.md)
- [新建版本 API](upload.md)