201 lines
6.1 KiB
Markdown
201 lines
6.1 KiB
Markdown
# 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)
|