ModReleaser/docs/modrinth/upload.md

# 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)