6.1 KiB
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 页面生成 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 中的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 结构
{
"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— 工具
成功响应
{
"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 结构
{
"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 将返回失败。
成功响应
{
"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。