ModReleaser/docs/curseforge/upload.md

# CurseForge Upload API

> 基于 CurseForge 官方 API 文档及实测整理。
>
> API 基础地址：`https://minecraft.curseforge.com`，**必须带浏览器 `User-Agent` 请求头**，否则 Cloudflare 会拦截返回 403。
>
> 推荐 User-Agent：`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`

---

## 生成 Token

在 [API Tokens](https://authors.curseforge.com/account/api-tokens) 页面生成 API Token。

## 认证

通过以下两种方式之一传递 Token：

- HTTP Header：`X-Api-Token: <token>`
- Query String：`?token=<token>`

---

## Game Version Types API

```
GET https://minecraft.curseforge.com/api/game/version-types
```

> **注意：** 此端点必须带浏览器 `User-Agent` 请求头，否则会被 Cloudflare 拦截返回 403。
>
> 推荐值：`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`

返回版本类型列表，直接返回 JSON 数组，每个对象包含：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int | 版本类型 ID（即 `gameVersionTypeID`） |
| `name` | string | 类型名称 |
| `slug` | string | 类型标识 |

其中 `id: 68441, name: "Modloader"` 对应 Modloader 分类。

`id: 75208, name: "Environment"` 对应运行环境，包含 `name: "Client"` 和 `name: "Server"` 两个 Game Version。

## Game Versions API

```
GET https://minecraft.curseforge.com/api/game/versions
```

> **注意：** 此端点必须带浏览器 `User-Agent` 请求头，否则会被 Cloudflare 拦截返回 403。
>
> 推荐值：`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`

返回 Minecraft 版本列表，直接返回 JSON 数组（无 `{"data": ...}` 包装），每个对象包含：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int | 版本 ID（用于上传时的 `gameVersions` 字段） |
| `gameVersionTypeID` | int | 版本类型 ID |
| `name` | string | 版本名称（如 `1.21.5`） |
| `slug` | string | 版本标识（如 `1-21-5`） |
| `apiVersion` | string \| null | API 版本号 |

> **注意：** Game Versions 列表并非仅包含游戏版本号，而是将 Mod Loader（Forge、Fabric 等）、Environment（Client、Server）甚至 Java 版本都混在一起。具体某个版本属于哪个类型，看它的 `gameVersionTypeID`，对应 [Game Version Types API](#game-version-types-api) 中的 `id`。

---

## Project Upload File API

```
POST https://minecraft.curseforge.com/api/projects/{projectId}/upload-file
Content-Type: multipart/form-data
```

上传文件到项目。`projectId` 可在项目概览页面的 URL 中找到。

### 请求字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `metadata` | string (JSON) | 文件元数据（见下方） |
| `file` | file | 要上传的实际文件 |

### metadata JSON 结构

```jsonc
{
    "changelog": "更新日志内容",          // 必填。支持 HTML / Markdown（需设置 changelogType）
    "changelogType": "markdown",         // 可选，默认 "text"。可选值: "text", "html", "markdown"
    "displayName": "Foo",               // 可选，站点上显示的文件友好名称
    "parentFileID": 42,                 // 可选，父文件 ID
    "gameVersions": [157, 158],         // 可选，支持的 Game Version ID 列表（通过 Game Versions API 获取）。若提供 parentFileID 则不支持此字段
    "releaseType": "release",             // 必填。可选值: "alpha", "beta", "release"
    "isMarkedForManualRelease": false,  // 可选，若为 true，审核通过后不会立即发布，可手动选择发布时间
    "relations": {
        "projects": [{
            "slug": "mantle",           // 关联项目的 slug
            "projectID": 74924,        // 可选，用于精确匹配项目
            "type": "requiredDependency" // 关联类型，可选值见下方
        }]
    }
}
```

**relations.type 可选值：**

- `embeddedLibrary` — 内嵌库
- `incompatible` — 不兼容
- `optionalDependency` — 可选依赖
- `requiredDependency` — 必需依赖
- `tool` — 工具

### 成功响应

```jsonc
{
    "id": 20402    // 新建文件的 ID
}
```

---

## Project File Management API

```
POST https://minecraft.curseforge.com/api/projects/{projectId}/update-file
Content-Type: multipart/form-data
```

更新已上传的文件信息。

### 请求字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `metadata` | string (JSON) | 文件更新元数据（见下方） |

### metadata JSON 结构

```jsonc
{
    "fileID": 20402,                     // 必填，要更新的文件 ID

    // 以下字段均为可选，可任意组合，但至少要包含一个
    "changelog": "更新日志内容",
    "changelogType": "markdown",         // 可选值: "text", "html", "markdown"，默认 "text"
    "displayName": "Foo",
    "gameVersions": [157, 158],
    "releaseType": "release",              // 可选值: "alpha", "beta", "release"
    "relations": {
        "projects": [{
            "slug": "mantle",
            "projectID": 74924,
            "type": "requiredDependency"
        }]
    }
}
```

> **注意：** 若未填写任何可选字段，API 将返回失败。

### 成功响应

```jsonc
{
    "id": 20402    // 被更新文件的 ID
}
```

---

## Maven

CurseForge 提供 Maven 端点，可在构建脚本中引用依赖。

```
https://www.curseforge.com/api/maven/{projectSlug}/{mavenArtifact}/{mavenVersion}/{projectFileNameArtifact}-{projectFileNameVersion}-{projectFileNameTag}.jar
```

**URL 参数说明：**

| 参数 | 说明 |
|------|------|
| `{projectSlug}` | 项目的 slug |
| `{mavenArtifact}` | 文件名 artifact |
| `{mavenVersion}` | 版本号，或使用 `release` 获取最新版 |
| `{projectFileNameArtifact}` | 同 `mavenArtifact` |
| `{projectFileNameVersion}` | 同 `mavenVersion` |
| `{projectFileNameTag}` | 文件名标签（如 `universal`、`dev`） |

> **注意：** Maven 认证不支持 Header 方式，需将 API Key 直接编入 Maven URL。

---

## 参考链接

- [CurseForge API Tokens](https://authors.curseforge.com/account/api-tokens)
- [官方文档原文](https://support.curseforge.com/support/solutions/articles/9000197321-curseforge-upload-api)