Add documentation for Mod Releaser project
This commit is contained in:
CPTProgrammer
@@ -0,0 +1,284 @@
|
||||
# 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)
|
||||
@@ -0,0 +1,402 @@
|
||||
# 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)
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,407 @@
|
||||
# Modrinth 新建版本 API 使用文档
|
||||
|
||||
本文档详细描述如何通过 Modrinth API 创建一个新版本，包括上传模组主文件（`.jar`）和一个 `-sources.jar` 附属文件。
|
||||
|
||||
---
|
||||
|
||||
## 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **端点** | `POST /version` |
|
||||
| **生产环境** | `https://api.modrinth.com/v2/version` |
|
||||
| **测试环境** | `https://staging-api.modrinth.com/v2/version` |
|
||||
| **Content-Type** | `multipart/form-data` |
|
||||
| **认证** | 必需 — Personal Access Token (PAT) |
|
||||
| **所需 Scope** | `VERSION_CREATE` |
|
||||
| **成功响应码** | `200` |
|
||||
| **成功响应体** | [Version](#响应格式) 对象 |
|
||||
|
||||
---
|
||||
|
||||
## 认证
|
||||
|
||||
所有创建数据的请求都需要认证。你需要一个 **Personal Access Token**（PAT），在 [Modrinth 用户设置](https://modrinth.com/settings/account) 中生成。
|
||||
|
||||
创建版本需要 PAT 具有 `VERSION_CREATE` 权限范围。
|
||||
|
||||
将 Token 放在 `Authorization` 请求头中：
|
||||
|
||||
```
|
||||
Authorization: mrp_RNtLRSPmGj2pd1v1ubi52nX7TJJM9sznrmwhAuj511oe4t1jAqAQ3D6Wc8Ic
|
||||
```
|
||||
|
||||
> **注意：** 需要在 `upload.md` 中提供有效的 Token。
|
||||
|
||||
同时，Modrinth **要求**提供一个可唯一标识的 `User-Agent` 请求头：
|
||||
|
||||
```
|
||||
User-Agent: github_username/project_name/1.0.0 (contact@example.com)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 请求格式
|
||||
|
||||
请求是一个 **multipart/form-data** 请求，必须包含至少两个表单字段：
|
||||
|
||||
- **`data`**：一个 JSON 字符串，包含版本元数据（见下方 [data JSON 结构](#data-json-结构)）。
|
||||
- **一个或多个文件字段**：包含要上传的 `.jar`、`.mrpack`、`.zip` 或 `.litemod` 文件。文件字段名可自定义。
|
||||
|
||||
### 重要概念区分：multipart 字段名 vs 文件名
|
||||
|
||||
在 multipart 请求中，每个文件字段都有**两个不同的名字**：
|
||||
|
||||
```
|
||||
-F "main-file=@./build/libs/my-mod-1.0.0.jar"
|
||||
^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
|
||||
multipart 字段名 (field name) 文件名 (filename)
|
||||
```
|
||||
|
||||
- **multipart 字段名**（如 `main-file`）：在请求体中标识这一部分数据的 key，由你自定义。
|
||||
- **文件名**（如 `my-mod-1.0.0.jar`）：被上传文件的原始名称。
|
||||
|
||||
> **关键规则：`file_parts`、`primary_file`、`file_types` 的 key 全部使用 multipart 字段名，而不是文件名。**
|
||||
|
||||
### `file_parts` — 声明有哪些文件
|
||||
|
||||
在 `data` JSON 的 `file_parts` 数组中列出所有承载文件的 **multipart 字段名**，并在 `primary_file` 中指定哪个是主文件。
|
||||
|
||||
```json
|
||||
{
|
||||
"file_parts": ["main-file", "sources-file", "dev-file"],
|
||||
"primary_file": "main-file"
|
||||
}
|
||||
```
|
||||
|
||||
### `file_types` — 标记附属文件类型
|
||||
|
||||
`file_types` 是一个 **对象（map）**，**key 是 multipart 字段名**（与 `file_parts` 中的值一致），value 是该文件的类型枚举值。用于标记 `-sources.jar`、`-dev.jar` 等附属文件。
|
||||
|
||||
可用的文件类型（`FileTypeEnum`）：
|
||||
|
||||
| 值 | 含义 |
|
||||
|----|------|
|
||||
| `required-resource-pack` | 必需资源包 |
|
||||
| `optional-resource-pack` | 可选资源包 |
|
||||
| `sources-jar` | 源代码 JAR |
|
||||
| `dev-jar` | 开发版 JAR（包含未混淆的类） |
|
||||
| `javadoc-jar` | Javadoc JAR |
|
||||
| `unknown` | 未知类型 |
|
||||
| `signature` | 签名文件 |
|
||||
|
||||
**标记 sources.jar 的示例：**
|
||||
|
||||
```json
|
||||
{
|
||||
"file_types": {
|
||||
"sources-file": "sources-jar"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 上例中 `"sources-file"` 是 multipart 字段名，需要在 `file_parts` 中同步出现。
|
||||
|
||||
---
|
||||
|
||||
## data JSON 结构
|
||||
|
||||
`data` 字段的值是一个 JSON 字符串，对应 `CreatableVersion` schema，它扩展了 `BaseVersion`。
|
||||
|
||||
### 顶层结构（`CreateVersionBody`）
|
||||
|
||||
```json
|
||||
{
|
||||
"data": "{ ... CreatableVersion JSON ... }"
|
||||
}
|
||||
```
|
||||
|
||||
### CreatableVersion 字段一览
|
||||
|
||||
#### 必填字段
|
||||
|
||||
| 字段 | 类型 | 说明 | 示例 |
|
||||
|------|------|------|------|
|
||||
| `project_id` | `string` | 目标项目的 ID（8 位 base62） | `"AABBCCDD"` |
|
||||
| `file_parts` | `string[]` | 所有承载文件的 **multipart 字段名** 列表 | `["main-file", "sources-file"]` |
|
||||
| `name` | `string` | 版本名称 | `"Version 1.0.0"` |
|
||||
| `version_number` | `string` | 版本号，建议遵循语义化版本 | `"1.0.0"` |
|
||||
| `game_versions` | `string[]` | 支持的 Minecraft 版本列表 | `["1.20.1", "1.20.4"]` |
|
||||
| `version_type` | `string` | 发布渠道：`release`、`beta`、`alpha` | `"release"` |
|
||||
| `loaders` | `string[]` | 支持的模组加载器列表 | `["fabric", "forge"]` |
|
||||
| `featured` | `boolean` | 是否为精选版本 | `false` |
|
||||
| `dependencies` | `object[]` | 依赖列表（可为空数组 `[]`） | 见下方 [依赖结构](#依赖结构) |
|
||||
|
||||
#### 可选字段
|
||||
|
||||
| 字段 | 类型 | 说明 | 示例 |
|
||||
|------|------|------|------|
|
||||
| `primary_file` | `string` | 主文件的 **multipart 字段名**。不提供时推断第一个文件为主文件 | `"main-file"` |
|
||||
| `changelog` | `string \| null` | 更新日志（Markdown/纯文本） | `"修复了若干 Bug"` |
|
||||
| `status` | `string` | 版本状态：`listed`、`archived`、`draft`、`unlisted`、`scheduled`、`unknown`。默认为 `listed` | `"listed"` |
|
||||
| `requested_status` | `string \| null` | 请求的状态（用于审核流程）：`listed`、`archived`、`draft`、`unlisted` | `"listed"` |
|
||||
| `environment` | `string` | 目标环境，见下方枚举 | `"client_and_server"` |
|
||||
| `file_types` | `object` | **multipart 字段名** → 文件类型的映射 | `{"sources-file": "sources-jar"}` |
|
||||
|
||||
#### `environment` 枚举值
|
||||
|
||||
所有值来自 Modrinth 前端源码 [environments.ts](https://github.com/modrinth/code/blob/main/packages/ui/src/components/project/settings/environment/environments.ts)。以下按前端 UI 的层级结构排列，只有 **Server-side only** 和 **Client and server** 是带子选项的大类，其余为单选：
|
||||
|
||||
| 大类（前端 UI） | 子项标题 | API 值 | 说明 |
|
||||
|----------------|---------|--------|------|
|
||||
| *（无分类，单选）* | Unknown environment | `unknown` | 未指定或无法确定环境 |
|
||||
| Client-side only | — | `client_only` | 所有功能在客户端运行，兼容原版服务端 |
|
||||
| **Server-side only** | Works in singleplayer too | `server_only` | 所有功能在服务端运行，兼容原版客户端；也支持单人模式的内置服务端 |
|
||||
| | Dedicated server only | `dedicated_server_only` | 所有功能在服务端运行，兼容原版客户端；仅在专用服务器上工作 |
|
||||
| **Client and server** | Required on both | `client_and_server` | 客户端和服务端都必须安装 |
|
||||
| | Optional on client | `server_only_client_optional` | 主要为服务端功能，客户端安装可增强体验 |
|
||||
| | Optional on server | `client_only_server_optional` | 主要为客户端功能，服务端安装可增强体验 |
|
||||
| | Optional on both, works best when installed on both sides | `client_or_server_prefers_both` | 双方都装体验最佳 |
|
||||
| | Optional on both, works the same if installed on either side | `client_or_server` | 单独安装任一侧效果相同 |
|
||||
| Singleplayer only | — | `singleplayer_only` | 仅在单人模式或未连接多人服务器时可用 |
|
||||
|
||||
### 依赖结构
|
||||
|
||||
`dependencies` 数组中每个依赖对象至少需要 `dependency_type` 字段：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 | 示例 |
|
||||
|------|------|------|------|------|
|
||||
| `dependency_type` | `string` | ✅ | 依赖类型：`required`、`optional`、`incompatible`、`embedded` | `"required"` |
|
||||
| `project_id` | `string \| null` | ❌ | 依赖的项目 ID | `"P7dR8mSH"` (Fabric API) |
|
||||
| `version_id` | `string \| null` | ❌ | 依赖的具体版本 ID；为 `null` 时匹配最新版 | `"IIJJKKLL"` |
|
||||
| `file_name` | `string \| null` | ❌ | 依赖文件名，主要用于整合包中的外部依赖 | `"fabric-api-0.92.0.jar"` |
|
||||
|
||||
> **注意：** `project_id` 和 `version_id` 二者至少提供一个，否则依赖关系无法解析。
|
||||
|
||||
**Fabric API 依赖示例：**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependency_type": "required",
|
||||
"project_id": "P7dR8mSH"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 完整请求示例
|
||||
|
||||
以下是一个使用 cURL 上传一个主 jar 和一个 sources.jar 的完整请求。
|
||||
|
||||
### 准备
|
||||
|
||||
假设：
|
||||
- 项目 ID 为 `AABBCCDD`
|
||||
- 主文件为 `my-mod-1.0.0.jar`
|
||||
- 源代码文件为 `my-mod-1.0.0-sources.jar`
|
||||
|
||||
### cURL 命令
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.modrinth.com/v2/version" \
|
||||
-H "Authorization: YOUR_PAT_TOKEN" \
|
||||
-H "User-Agent: your_username/your_project/1.0.0" \
|
||||
-F "data={
|
||||
\"project_id\": \"AABBCCDD\",
|
||||
\"file_parts\": [\"main-file\", \"sources-file\"],
|
||||
\"primary_file\": \"main-file\",
|
||||
\"name\": \"Version 1.0.0\",
|
||||
\"version_number\": \"1.0.0\",
|
||||
\"changelog\": \"## 更新内容\n\n- 新增了某某功能\n- 修复了某某 Bug\",
|
||||
\"dependencies\": [
|
||||
{
|
||||
\"dependency_type\": \"required\",
|
||||
\"project_id\": \"P7dR8mSH\"
|
||||
}
|
||||
],
|
||||
\"game_versions\": [\"1.20.1\", \"1.20.4\"],
|
||||
\"version_type\": \"release\",
|
||||
\"loaders\": [\"fabric\"],
|
||||
\"featured\": false,
|
||||
\"status\": \"listed\",
|
||||
\"environment\": \"client_and_server\",
|
||||
\"file_types\": {
|
||||
\"sources-file\": \"sources-jar\"
|
||||
}
|
||||
}" \
|
||||
-F "main-file=@./build/libs/my-mod-1.0.0.jar" \
|
||||
-F "sources-file=@./build/libs/my-mod-1.0.0-sources.jar"
|
||||
```
|
||||
|
||||
### Node.js (fetch) 示例
|
||||
|
||||
```js
|
||||
const fs = require("fs");
|
||||
|
||||
const TOKEN = "YOUR_PAT_TOKEN";
|
||||
const PROJECT_ID = "AABBCCDD";
|
||||
|
||||
const form = new FormData();
|
||||
|
||||
const metadata = {
|
||||
project_id: PROJECT_ID,
|
||||
file_parts: ["main-file", "sources-file"],
|
||||
primary_file: "main-file",
|
||||
name: "Version 1.0.0",
|
||||
version_number: "1.0.0",
|
||||
changelog: "## 更新内容\n\n- 新增了某某功能\n- 修复了某某 Bug",
|
||||
dependencies: [
|
||||
{ dependency_type: "required", project_id: "P7dR8mSH" }
|
||||
],
|
||||
game_versions: ["1.20.1", "1.20.4"],
|
||||
version_type: "release",
|
||||
loaders: ["fabric"],
|
||||
featured: false,
|
||||
status: "listed",
|
||||
environment: "client_and_server",
|
||||
file_types: {
|
||||
"sources-file": "sources-jar"
|
||||
}
|
||||
};
|
||||
|
||||
form.append("data", JSON.stringify(metadata));
|
||||
form.append("main-file", new Blob([fs.readFileSync("./build/libs/my-mod-1.0.0.jar")]), "my-mod-1.0.0.jar");
|
||||
form.append("sources-file", new Blob([fs.readFileSync("./build/libs/my-mod-1.0.0-sources.jar")]), "my-mod-1.0.0-sources.jar");
|
||||
|
||||
const response = await fetch("https://api.modrinth.com/v2/version", {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Authorization": TOKEN,
|
||||
"User-Agent": "your_username/your_project/1.0.0"
|
||||
},
|
||||
body: form
|
||||
});
|
||||
|
||||
const result = await response.json();
|
||||
console.log(result);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 响应格式
|
||||
|
||||
成功创建后返回一个 [Version](#version-对象) 对象，HTTP 状态码 `200`。
|
||||
|
||||
### Version 对象
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IIJJKKLL",
|
||||
"project_id": "AABBCCDD",
|
||||
"author_id": "EEFFGGHH",
|
||||
"name": "Version 1.0.0",
|
||||
"version_number": "1.0.0",
|
||||
"changelog": "## 更新内容\n\n- 新增了某某功能\n- 修复了某某 Bug",
|
||||
"date_published": "2025-01-01T00:00:00Z",
|
||||
"downloads": 0,
|
||||
"version_type": "release",
|
||||
"status": "listed",
|
||||
"requested_status": null,
|
||||
"game_versions": ["1.20.1", "1.20.4"],
|
||||
"loaders": ["fabric"],
|
||||
"featured": false,
|
||||
"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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
响应中 `files` 数组的每个文件对象包含：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `hashes` | 文件哈希，包含 `sha512` 和 `sha1` |
|
||||
| `url` | 文件直链 |
|
||||
| `filename` | 文件名 |
|
||||
| `primary` | 是否为主文件 |
|
||||
| `size` | 文件大小（字节） |
|
||||
| `file_type` | 文件类型（对于 sources.jar 为 `"sources-jar"`） |
|
||||
|
||||
---
|
||||
|
||||
## 错误码
|
||||
|
||||
| 状态码 | 错误类型 | 说明 |
|
||||
|--------|----------|------|
|
||||
| `400` | `InvalidInputError` | 请求参数无效，详见响应中的 `description`。常见原因：缺少必填字段、`game_versions` 或 `loaders` 值不合法、文件格式不被接受 |
|
||||
| `401` | `AuthError` | Token 无效、未提供 Token，或 Token 不包含 `VERSION_CREATE` 权限范围 |
|
||||
| `404` | — | 目标项目 `project_id` 不存在 |
|
||||
|
||||
---
|
||||
|
||||
## 注意事项与最佳实践
|
||||
|
||||
### 1. 必须至少上传一个文件
|
||||
|
||||
除非版本 `status` 设置为 `draft`，否则每个新版本必须附带至少一个文件。接受的格式：`.mrpack`、`.jar`、`.zip`、`.litemod`。
|
||||
|
||||
### 2. `file_parts` / `file_types` / `primary_file` 全部使用 multipart 字段名
|
||||
|
||||
这三处字符串和实际表单字段名必须**严格匹配**，且它们指向的都是 **multipart 字段名**（如 `"main-file"`），不是文件名（如 `"my-mod-1.0.0.jar"`）。否则上传的文件不会被正确关联。
|
||||
|
||||
### 3. sources.jar 的正确做法
|
||||
|
||||
- 给 sources 文件随意命名 multipart 字段名（如 `"sources-file"`），将其列入 `file_parts`。
|
||||
- 在 `file_types` 中映射该 **multipart 字段名** → `"sources-jar"`。
|
||||
- **不要**将 sources 文件设为主文件（`primary_file` 应指向主 jar 的 multipart 字段名）。
|
||||
|
||||
### 4. `dependencies` 可以是空数组
|
||||
|
||||
如果该模组没有依赖（极少数情况），直接传 `[]` 即可。但 `dependencies` 字段本身是必填的。
|
||||
|
||||
### 5. 文件大小限制
|
||||
|
||||
Modrinth 对上传文件有大小限制。如果文件过大，可能收到 `400` 错误。建议保持在合理范围内（一般单个文件不超过 100MB）。
|
||||
|
||||
### 6. 版本号建议
|
||||
|
||||
`version_number` 理想上应遵循[语义化版本规范](https://semver.org/lang/zh-CN/)，便于 Modrinth 进行版本比较和用户理解。
|
||||
|
||||
### 7. 草稿版本
|
||||
|
||||
如果你想先上传版本而不立即公开，可将 `status` 设为 `draft`。草稿版本可以不附带文件。后续可通过 PATCH `/version/{id}` 修改状态为 `listed` 来发布。
|
||||
|
||||
### 8. 已有版本追加文件
|
||||
|
||||
如果版本已创建但需要追加文件，应使用 `POST /version/{id}/file` 端点（需要 `VERSION_WRITE` 权限范围）。
|
||||
|
||||
### 9. 环境与加载器的校验
|
||||
|
||||
`loaders` 和 `game_versions` 必须使用 Modrinth 认可的值。你可以通过以下端口查询可用值：
|
||||
- `GET /tag/loader` — 可用加载器
|
||||
- `GET /tag/game_version` — 可用 Minecraft 版本
|
||||
|
||||
### 10. Rate Limit
|
||||
|
||||
Modrinth API 有频率限制：每 IP 每分钟最多 **300** 个请求。响应头中包含 `X-Ratelimit-Limit`、`X-Ratelimit-Remaining`、`X-Ratelimit-Reset`。
|
||||
|
||||
---
|
||||
|
||||
## 参考
|
||||
|
||||
- [Modrinth API 文档](https://docs.modrinth.com)
|
||||
- [Modrinth 创建 PAT](https://modrinth.com/settings/account)
|
||||
- [OpenAPI 规范文件](openapi.yml)
|
||||
- [Modrinth Labrinth 源码](https://github.com/modrinth/labrinth)
|
||||
- [语义化版本规范](https://semver.org)
|
||||
Reference in New Issue
Block a user