# Modrinth 获取版本信息 API 使用文档

本文档描述如何通过 Modrinth API 获取项目的版本列表以及每个版本的详细信息，包括版本名（`name`）、版本号（`version_number`）、文件名（`filename`）、下载地址等。

---

## 基本信息

所有版本读取接口均为 **公开接口，无需认证**。但如果项目包含 `draft`（草稿）状态的版本，获取它们可能需要认证。

| 项目 | 内容 |
|------|------|
| **生产环境** | `https://api.modrinth.com/v2` |
| **测试环境** | `https://staging-api.modrinth.com/v2` |
| **认证** | 公开接口无需认证；获取草稿版本需要 PAT |
| **Rate Limit** | 每 IP 每分钟 300 请求 |

---

## 接口一：列出项目的所有版本

获取指定项目下的全部版本列表。这是获取版本信息最常用的入口。

| 项目 | 内容 |
|------|------|
| **端点** | `GET /project/{id\|slug}/version` |
| **认证** | 否（公开） |
| **成功响应码** | `200` |
| **响应体** | `Version[]` — Version 对象数组 |

### 路径参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `id\|slug` | 项目的 8 位 base62 ID 或 slug（别名） | `AABBCCDD` 或 `my-mod` |

### 查询参数（可选，用于过滤）

| 参数 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `loaders` | `string` | 按加载器过滤，JSON 数组字符串 | `'["fabric"]'` |
| `game_versions` | `string` | 按 Minecraft 版本过滤，JSON 数组字符串 | `'["1.20.4"]'` |
| `featured` | `boolean` | 按是否精选过滤 | `true` |
| `include_changelog` | `boolean` | 是否在响应中包含 `changelog` 字段。**强烈建议设为 `false`** 以减小响应体，除非确实需要更新日志内容 | `false` |

### 请求示例

**获取某项目的全部版本（不含 changelog）：**

```bash
curl "https://api.modrinth.com/v2/project/AABBCCDD/version?include_changelog=false"
```

**按加载器和游戏版本过滤：**

```bash
curl "https://api.modrinth.com/v2/project/AABBCCDD/version?loaders=%5B%22fabric%22%5D&game_versions=%5B%221.20.4%22%5D"
```

> 注意：`loaders` 和 `game_versions` 的值需要是 JSON 数组字符串（如 `["fabric"]`），在 URL 中需要做 URL 编码。`[...]` 编码后为 `%5B...%5D`。

**Node.js (fetch) 示例：**

```js
const projectId = "AABBCCDD";

const url = new URL(`https://api.modrinth.com/v2/project/${projectId}/version`);
url.searchParams.set("include_changelog", "false");

const response = await fetch(url);
const versions = await response.json();

for (const v of versions) {
  console.log(`版本名: ${v.name}`);
  console.log(`版本号: ${v.version_number}`);
  for (const f of v.files) {
    console.log(`  文件: ${f.filename} (${f.size} bytes) ${f.primary ? "[主文件]" : ""}`);
  }
}
```

---

## 接口二：获取单个版本

根据版本 ID 获取某个版本的完整信息。

| 项目 | 内容 |
|------|------|
| **端点** | `GET /version/{id}` |
| **认证** | 否（公开） |
| **成功响应码** | `200` |
| **响应体** | `Version` 对象 |

### 路径参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `id` | 版本 ID（8 位 base62 字符串） | `IIJJKKLL` |

### 请求示例

```bash
curl "https://api.modrinth.com/v2/version/IIJJKKLL"
```

```js
const versionId = "IIJJKKLL";
const response = await fetch(`https://api.modrinth.com/v2/version/${versionId}`);
const version = await response.json();
console.log(version.name, version.version_number);
```

---

## 接口三：通过项目 + 版本号获取版本

如果你知道项目 ID 和版本号（而非版本 ID），可以用此接口直接获取。

| 项目 | 内容 |
|------|------|
| **端点** | `GET /project/{id\|slug}/version/{id\|number}` |
| **认证** | 否（公开） |
| **成功响应码** | `200` |
| **响应体** | `Version` 对象 |

### 路径参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `id\|slug` | 项目 ID 或 slug | `AABBCCDD` |
| `id\|number` | 版本 ID 或版本号字符串 | `1.0.0` 或 `IIJJKKLL` |

> **注意：** 如果版本号匹配到多个版本，只会返回 **最旧的** 那个。建议使用版本 ID 获得精确结果。

### 请求示例

```bash
curl "https://api.modrinth.com/v2/project/AABBCCDD/version/1.0.0"
```

---

## 接口四：批量获取多个版本

一次请求获取多个指定版本的信息。

| 项目 | 内容 |
|------|------|
| **端点** | `GET /versions` |
| **认证** | 否（公开） |
| **成功响应码** | `200` |
| **响应体** | `Version[]` — Version 对象数组 |

### 查询参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| `ids` | `string` | ✅ | JSON 数组字符串，包含版本 ID 列表 | `'["IIJJKKLL", "MMNNOOPP"]'` |

### 请求示例

```bash
curl "https://api.modrinth.com/v2/versions?ids=%5B%22IIJJKKLL%22%2C%22MMNNOOPP%22%5D"
```

```js
const versionIds = ["IIJJKKLL", "MMNNOOPP"];
const url = new URL("https://api.modrinth.com/v2/versions");
url.searchParams.set("ids", JSON.stringify(versionIds));
const response = await fetch(url);
const versions = await response.json();
```

---

## 响应格式

### Version 对象结构

```json
{
  "id": "IIJJKKLL",
  "project_id": "AABBCCDD",
  "author_id": "EEFFGGHH",
  "name": "Version 1.0.0",
  "version_number": "1.0.0",
  "changelog": "## 更新内容\n\n- 修复了若干 Bug",
  "date_published": "2025-01-01T00:00:00Z",
  "downloads": 1024,
  "version_type": "release",
  "status": "listed",
  "requested_status": null,
  "game_versions": ["1.20.1", "1.20.4"],
  "loaders": ["fabric"],
  "featured": false,
  "dependencies": [
    {
      "dependency_type": "required",
      "project_id": "P7dR8mSH",
      "version_id": null,
      "file_name": null
    }
  ],
  "files": [
    {
      "hashes": {
        "sha512": "93ecf5fe...",
        "sha1": "c84dd4b3..."
      },
      "url": "https://cdn.modrinth.com/data/AABBCCDD/versions/1.0.0/my-mod-1.0.0.jar",
      "filename": "my-mod-1.0.0.jar",
      "primary": true,
      "size": 1097270,
      "file_type": null
    },
    {
      "hashes": {
        "sha512": "ab12cd34...",
        "sha1": "ef56gh78..."
      },
      "url": "https://cdn.modrinth.com/data/AABBCCDD/versions/1.0.0/my-mod-1.0.0-sources.jar",
      "filename": "my-mod-1.0.0-sources.jar",
      "primary": false,
      "size": 543210,
      "file_type": "sources-jar"
    }
  ]
}
```

### 关键字段说明

#### Version 顶层字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | `string` | 版本唯一 ID（8 位 base62） |
| `project_id` | `string` | 所属项目 ID |
| `author_id` | `string` | 发布者用户 ID |
| `name` | `string` | **版本名称**（如 `"Version 1.0.0"`） |
| `version_number` | `string` | **版本号**（如 `"1.0.0"`，建议遵循语义化版本） |
| `changelog` | `string \| null` | 更新日志文本（若使用 `include_changelog=false` 则为 `null`） |
| `date_published` | `string` | 发布时间（ISO-8601 格式） |
| `downloads` | `integer` | 下载次数 |
| `version_type` | `string` | 发布渠道：`release`、`beta`、`alpha` |
| `status` | `string` | 版本状态：`listed`、`archived`、`draft`、`unlisted`、`scheduled` |
| `game_versions` | `string[]` | 支持的 Minecraft 版本列表 |
| `loaders` | `string[]` | 支持的加载器列表 |
| `featured` | `boolean` | 是否为精选版本 |
| `dependencies` | `object[]` | 依赖列表（结构见下方） |
| `files` | `object[]` | 该版本的所有文件列表 |

#### dependencies 数组项

| 字段 | 类型 | 说明 |
|------|------|------|
| `dependency_type` | `string` | `required`、`optional`、`incompatible`、`embedded` |
| `project_id` | `string \| null` | 依赖的项目 ID |
| `version_id` | `string \| null` | 依赖的具体版本 ID |
| `file_name` | `string \| null` | 依赖文件名 |

#### files 数组项（最常需要关注的字段）

| 字段 | 类型 | 说明 |
|------|------|------|
| `filename` | `string` | **文件名**（如 `"my-mod-1.0.0.jar"`） |
| `url` | `string` | 文件直链下载地址 |
| `size` | `integer` | 文件大小（字节） |
| `primary` | `boolean` | 是否为主文件。每个版本最多一个主文件；若没有一个标记为 `true`，则推断第一个文件为主文件 |
| `hashes.sha1` | `string` | 文件的 SHA-1 哈希 |
| `hashes.sha512` | `string` | 文件的 SHA-512 哈希 |
| `file_type` | `string \| null` | 文件类型：`sources-jar`、`dev-jar`、`javadoc-jar`、`required-resource-pack`、`optional-resource-pack`、`unknown`、`signature`。普通主 jar 为 `null` |

---

## 常见使用场景

### 场景 1：获取项目的最新版本

从版本列表中取第一个（通常是时间最新的），再拿到文件信息：

```js
const projectSlug = "my-mod";
const response = await fetch(
  `https://api.modrinth.com/v2/project/${projectSlug}/version?include_changelog=false`
);
const versions = await response.json();

const latest = versions[0];
console.log(`版本: ${latest.name} (${latest.version_number})`);
console.log(`主文件: ${latest.files.find(f => f.primary).filename}`);
```

### 场景 2：列出某版本的所有文件及其类型

```js
const versionId = "IIJJKKLL";
const response = await fetch(`https://api.modrinth.com/v2/version/${versionId}`);
const version = await response.json();

for (const file of version.files) {
  const typeLabel = file.file_type ?? "主 jar";
  console.log(`[${typeLabel}] ${file.filename} — ${file.url}`);
}
```

输出示例：

```
[主 jar] my-mod-1.0.0.jar — https://cdn.modrinth.com/.../my-mod-1.0.0.jar
[sources-jar] my-mod-1.0.0-sources.jar — https://cdn.modrinth.com/.../my-mod-1.0.0-sources.jar
```

### 场景 3：下载版本的主文件（通过直链）

```js
const version = await fetch("https://api.modrinth.com/v2/version/IIJJKKLL").then(r => r.json());
const primaryFile = version.files.find(f => f.primary) ?? version.files[0];

const fileBuffer = await fetch(primaryFile.url).then(r => r.arrayBuffer());
require("fs").writeFileSync(primaryFile.filename, Buffer.from(fileBuffer));
```

### 场景 4：仅获取特定加载器 + 游戏版本的版本

```js
const projectId = "AABBCCDD";
const url = new URL(`https://api.modrinth.com/v2/project/${projectId}/version`);
url.searchParams.set("loaders", JSON.stringify(["fabric"]));
url.searchParams.set("game_versions", JSON.stringify(["1.20.4"]));
url.searchParams.set("include_changelog", "false");

const versions = await fetch(url).then(r => r.json());
for (const v of versions) {
  console.log(`${v.name} (${v.version_number}) — ${v.files.find(f => f.primary)?.filename}`);
}
```

---

## 错误码

| 状态码 | 说明 |
|--------|------|
| `200` | 成功 |
| `404` | 项目不存在、版本不存在，或无权访问（如草稿版本） |

---

## 注意事项与最佳实践

### 1. 始终使用 `include_changelog=false`

除非你真的需要每个版本的 changelog 文本，否则务必传入 `include_changelog=false`。changelog 可能非常长，会显著增大响应体、降低请求速度。Modrinth 官方也强烈建议这样做。

### 2. 主文件的判断规则

`files` 数组中若有一个 `primary: true`，那就是主文件。如果一个都没有，则**推断第一个文件为主文件**。不要假定 `files[0]` 一定是主 jar——sources jar 也可能排在首位。

### 3. 版本列表的排序

`GET /project/{id|slug}/version` 返回的列表**按发布日期降序排列**（最新的在前）。若需确定顺序，请以 `date_published` 字段为准。

### 4. 别忘了 User-Agent

即使是公开 GET 请求，Modrinth 也要求设置 `User-Agent` 请求头：

```
User-Agent: your_username/your_project/1.0.0 (contact@example.com)
```

### 5. 通过 slug 访问更易读

项目标识符支持 slug（如 `my-mod`）而非只能用 ID（如 `AABBCCDD`），对于调试和可读性更有帮助。但 slug 可能被项目所有者修改，长期存储建议使用 ID。

### 6. 版本号可能不唯一

`GET /project/{id|slug}/version/{id\|number}` 在使用版本号查找时，若遇到重名只返回最旧的那个。精确获取请使用版本 ID。

### 7. 分页

`GET /project/{id|slug}/version` **不支持分页参数**，会一次性返回该项目所有版本。对于版本数量极多的项目，响应体可能较大，此时推荐结合 `loaders` 和 `game_versions` 过滤。

---

## 可用加载器与游戏版本查询

如果你不确定 `loaders` 或 `game_versions` 过滤参数应填什么值，可以通过标签接口查询所有合法值：

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

---

## 参考

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