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）；修改版本不需要重新上传文件，只要传 JSON 即可。

---

路径参数

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

版本 ID 可通过 GET /project/{id|slug}/version 列表获取（见 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
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 的 FileTypeEnum 表	"sources-jar"

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

---

请求示例

修改兼容的 MC 版本范围

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) 示例

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 和发布渠道

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 注意事项第 8 条，当前项目尚未封装该接口）。

5. Rate Limit

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

---

参考

• Modrinth API 文档
• OpenAPI 规范文件（modifyVersion 操作 / EditableVersion schema）
• 新建版本 API 文档
• 获取版本信息 API 文档