ModReleaser/docs/modrinth/edit.md

# Modrinth 修改版本 API 使用文档

本文档描述如何通过 Modrinth API 修改一个**已有版本**的元数据，例如更新兼容的 Minecraft 版本范围（`game_versions`）、changelog、加载器列表等，无需重新上传文件。

---

## 基本信息

| 项目 | 内容 |
|------|------|
| **端点** | `PATCH /version/{id}` |
| **生产环境** | `https://api.modrinth.com/v2/version/{id}` |
| **测试环境** | `https://staging-api.modrinth.com/v2/version/{id}` |
| **Content-Type** | `application/json` |
| **认证** | 必需 — Personal Access Token (PAT) |
| **所需 Scope** | `VERSION_WRITE` |
| **成功响应码** | `204 No Content`（无响应体） |

> 创建版本用 `POST /version`（见 [upload.md](./upload.md)）；修改版本不需要重新上传文件，只要传 JSON 即可。

---

## 路径参数

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

> 版本 ID 可通过 `GET /project/{id|slug}/version` 列表获取（见 [get.md](./get.md)）。

---

## 请求体（EditableVersion）

请求体为 JSON，**所有字段均为可选，只需传入要修改的字段**，未传入的字段保持不变。

### 继承自 BaseVersion 的字段

| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `name` | `string` | 版本名称 | `"Version 1.0.0"` |
| `version_number` | `string` | 版本号 | `"1.0.0"` |
| `changelog` | `string \| null` | 更新日志（Markdown/纯文本） | `"修复了若干 Bug"` |
| `dependencies` | `object[]` | 依赖列表（整体替换），结构同创建版本 | 见 [upload.md](./upload.md#依赖结构) |
| `game_versions` | `string[]` | **支持的 Minecraft 版本列表（整体替换）** | `["1.21", "1.21.1"]` |
| `version_type` | `string` | 发布渠道：`release`、`beta`、`alpha` | `"release"` |
| `loaders` | `string[]` | 支持的加载器列表（整体替换） | `["fabric"]` |
| `featured` | `boolean` | 是否为精选版本 | `false` |
| `status` | `string` | 版本状态：`listed`、`archived`、`draft`、`unlisted`、`scheduled`、`unknown` | `"listed"` |
| `requested_status` | `string \| null` | 请求的状态（用于审核流程）：`listed`、`archived`、`draft`、`unlisted` | `"listed"` |

> **注意：** `game_versions`、`loaders`、`dependencies` 都是**整体替换**语义，传入的值会完全覆盖原值，而不是增量添加。修改兼容范围时应先读取版本当前的 `game_versions`，在此基础上增删后再整体提交。

### EditableVersion 独有字段

| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `primary_file` | `[string, string]` | 新的主文件，二元组 `[哈希算法, 哈希值]` | `["sha1", "aaaabbbb..."]` |
| `file_types` | `object[]` | 要修改文件类型的文件列表（见下方） | 见下方 |

#### `file_types` 数组项（EditableFileType）

通过文件哈希定位版本中的某个文件并修改其类型标记：

| 字段 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| `algorithm` | `string` | ✅ | 哈希算法（如 `sha1`、`sha512`） | `"sha1"` |
| `hash` | `string` | ✅ | 要修改的文件的哈希值 | `"aaaabbbb..."` |
| `file_type` | `string \| null` | ✅ | 新的文件类型；`null` 表示清除类型标记。枚举值见 [upload.md](./upload.md) 的 `FileTypeEnum` 表 | `"sources-jar"` |

> 文件的 `sha1` / `sha512` 哈希可从版本详情的 `files[].hashes` 字段获取（见 [get.md](./get.md)）。

---

## 请求示例

### 修改兼容的 MC 版本范围

```bash
curl -X PATCH "https://api.modrinth.com/v2/version/IIJJKKLL" \
  -H "Authorization: YOUR_PAT_TOKEN" \
  -H "User-Agent: your_username/your_project/1.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "game_versions": ["1.21", "1.21.1", "1.21.4"]
  }'
```

### Node.js (fetch) 示例

```js
const TOKEN = "YOUR_PAT_TOKEN";
const VERSION_ID = "IIJJKKLL";

const response = await fetch(
  `https://api.modrinth.com/v2/version/${VERSION_ID}`,
  {
    method: "PATCH",
    headers: {
      Authorization: TOKEN,
      "User-Agent": "your_username/your_project/1.0.0",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      game_versions: ["1.21", "1.21.1", "1.21.4"],
    }),
  },
);

// 成功时 response.status === 204，无响应体
console.log(response.status); // 204
```

### 同时修改 changelog 和发布渠道

```js
await fetch(`https://api.modrinth.com/v2/version/${VERSION_ID}`, {
  method: "PATCH",
  headers: {
    Authorization: TOKEN,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    changelog: "## 更新内容\n\n- 修复了某某 Bug",
    version_type: "beta",
  }),
});
```

---

## 响应

成功时返回 **`204 No Content`，无响应体**。修改后的完整版本信息可通过 `GET /version/{id}` 再次获取确认。

---

## 错误码

| 状态码 | 说明 |
|--------|------|
| `204` | 成功 |
| `401` | Token 无效、未提供 Token，或 Token 不包含 `VERSION_WRITE` 权限范围 |
| `404` | 版本不存在，或无权访问该版本 |

---

## 注意事项

### 1. 增量修改语义

PATCH 只更新传入的字段，未传入的字段保持服务器上的原值不变。这与 `POST /version`（全量创建）不同。

### 2. 数组字段是整体替换

`game_versions`、`loaders`、`dependencies` 传入后会**完全覆盖**原值。若只想"添加一个 MC 版本"，正确做法是：

1. `GET /version/{id}` 读取当前 `game_versions`；
2. 在数组中追加新版本号；
3. PATCH 提交完整的新数组。

### 3. 不要传递未修改的 status

客户端序列化请求体时，未显式设置的字段不应出现在 JSON 中。尤其注意不要让 `status` 被默认值（如 `"listed"`）填充，否则会意外改变版本状态（例如把 `draft` 变成 `listed`）。

### 4. 与"追加文件"的区别

本接口只修改元数据，不能上传新文件。向已有版本追加文件应使用 `POST /version/{id}/file`（见 [upload.md](./upload.md) 注意事项第 8 条，当前项目尚未封装该接口）。

### 5. Rate Limit

与 Modrinth 其他接口相同：每 IP 每分钟最多 **300** 个请求。

---

## 参考

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