# CurseForge Get Mod Files API

> 来源：https://docs.curseforge.com/rest-api/
>
> API 基础地址：`https://api.curseforge.com`，认证方式：Header `x-api-key: <token>`

---

## Get Mod Files

```
GET https://api.curseforge.com/v1/mods/{modId}/files
```

获取指定项目的所有文件。

### 参数

| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| `modId` | path | int32 | 是 | 项目 ID |
| `gameVersion` | query | string | 否 | 按游戏版本过滤 |
| `modLoaderType` | query | int | 否 | 按 Mod Loader 类型过滤（见下表） |
| `gameVersionTypeId` | query | int32 | 否 | 按 `gameVersionTypeId` 过滤 |
| `index` | query | int32 | 否 | 分页起始索引（从 0 开始，限制 `index + pageSize <= 10000`） |
| `pageSize` | query | int32 | 否 | 每页数量，默认/最大 50 |

**modLoaderType 枚举值：**

| 值 | 含义 |
|----|------|
| 0 | Any |
| 1 | Forge |
| 2 | Cauldron |
| 3 | LiteLoader |
| 4 | Fabric |
| 5 | Quilt |
| 6 | NeoForge |

### 成功响应

```jsonc
{
  "data": [
    {
      "id": 12345,                          // 文件 ID
      "gameId": 432,                        // 游戏 ID
      "modId": 789,                         // 项目 ID
      "isAvailable": true,                  // 是否可下载
      "displayName": "My Mod v1.0",         // 显示名称
      "fileName": "my-mod-1.0.jar",         // 文件名
      "releaseType": 1,                     // FileReleaseType
      "fileStatus": 10,                     // FileStatus
      "hashes": [
        { "value": "abc123...", "algo": 1 } // FileHash
      ],
      "fileDate": "2025-01-01T00:00:00Z",   // 文件时间戳
      "fileLength": 1048576,                // 文件大小（字节）
      "downloadCount": 5000,                // 下载次数
      "fileSizeOnDisk": 1048576,            // 磁盘占用
      "downloadUrl": "https://...",         // 下载地址
      "gameVersions": ["1.21.5", "1.21.4"], // 关联的游戏版本（字符串列表）
      "sortableGameVersions": [             // 排序用版本信息
        {
          "gameVersionName": "1.21.5",
          "gameVersionPadded": "0000000001.0000000021.0000000005",
          "gameVersion": "1.21.5",
          "gameVersionReleaseDate": "2025-04-01T00:00:00Z",
          "gameVersionTypeId": 83806
        }
      ],
      "dependencies": [                     // 依赖关系
        {
          "modId": 123,                     // 依赖的项目 ID
          "relationType": 3                 // FileRelationType
        }
      ],
      "exposeAsAlternative": false,
      "parentProjectFileId": null,
      "alternateFileId": null,
      "isServerPack": false,
      "serverPackFileId": null,
      "isEarlyAccessContent": false,
      "earlyAccessEndDate": null,
      "fileFingerprint": 1234567890,
      "modules": [
        { "name": "main", "fingerprint": 1234567890 }
      ]
    }
  ],
  "pagination": {
    "index": 0,         // 本次返回的起始索引
    "pageSize": 50,     // 请求的页大小
    "resultCount": 1,   // 本次实际返回数量
    "totalCount": 10    // 总文件数
  }
}
```

### 枚举值

**FileReleaseType**

| 值 | 含义 |
|----|------|
| 1 | Release |
| 2 | Beta |
| 3 | Alpha |

**FileRelationType**

| 值 | 含义 |
|----|------|
| 1 | EmbeddedLibrary |
| 2 | OptionalDependency |
| 3 | RequiredDependency |
| 4 | Tool |
| 5 | Incompatible |
| 6 | Include |

**FileStatus**

| 值 | 含义 |
|----|------|
| 1 | Processing |
| 2 | ChangesRequired |
| 3 | UnderReview |
| 4 | Approved |
| 5 | Rejected |
| 6 | MalwareDetected |
| 7 | Deleted |
| 8 | Archived |
| 9 | Testing |
| 10 | Released |
| 11 | ReadyForReview |
| 12 | Deprecated |
| 13 | Baking |
| 14 | AwaitingPublishing |
| 15 | FailedPublishing |
| 16 | Cooking |
| 17 | Cooked |
| 18 | UnderManualReview |
| 19 | ScanningForMalware |
| 20 | ProcessingFile |
| 21 | PendingRelease |
| 22 | ReadyForCooking |
| 23 | PostProcessing |

**HashAlgo**

| 值 | 含义 |
|----|------|
| 1 | Sha1 |
| 2 | Md5 |

---

## Schemas

### File

响应中 `data[]` 的元素类型。

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int32 | 文件 ID |
| `gameId` | int32 | 所属游戏 ID |
| `modId` | int32 | 所属项目 ID |
| `isAvailable` | boolean | 是否可下载 |
| `displayName` | string | 显示名称 |
| `fileName` | string | 文件名 |
| `releaseType` | FileReleaseType | 发布类型 |
| `fileStatus` | FileStatus | 文件状态 |
| `hashes` | FileHash[] | 文件哈希列表 |
| `fileDate` | string(date-time) | 文件时间戳 |
| `fileLength` | int64 | 文件大小（字节） |
| `downloadCount` | int64 | 下载次数 |
| `fileSizeOnDisk` | int64 \| null | 磁盘占用 |
| `downloadUrl` | string | 下载地址 |
| `gameVersions` | string[] | 关联的游戏版本字符串列表 |
| `sortableGameVersions` | SortableGameVersion[] | 排序用版本信息 |
| `dependencies` | FileDependency[] | 依赖关系 |
| `exposeAsAlternative` | boolean \| null | 是否暴露为替代版本 |
| `parentProjectFileId` | int32 \| null | 父项目文件 ID |
| `alternateFileId` | int32 \| null | 替代文件 ID |
| `isServerPack` | boolean \| null | 是否为服务端包 |
| `serverPackFileId` | int32 \| null | 服务端包文件 ID |
| `isEarlyAccessContent` | boolean \| null | 是否为抢先体验内容 |
| `earlyAccessEndDate` | string(date-time) \| null | 抢先体验结束日期 |
| `fileFingerprint` | int64 | 文件指纹 |
| `modules` | FileModule[] | 文件模块列表 |

### FileHash

| 字段 | 类型 | 说明 |
|------|------|------|
| `value` | string | 哈希值 |
| `algo` | int | 哈希算法（见 HashAlgo 枚举） |

### FileDependency

| 字段 | 类型 | 说明 |
|------|------|------|
| `modId` | int32 | 依赖的项目 ID |
| `relationType` | int | 关系类型（见 FileRelationType 枚举） |

### FileModule

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 模块名 |
| `fingerprint` | int64 | 模块指纹 |

### SortableGameVersion

| 字段 | 类型 | 说明 |
|------|------|------|
| `gameVersionName` | string | 原始版本名（如 `1.5b`） |
| `gameVersionPadded` | string | 补齐版本号（如 `0000000001.0000000005`），用于排序 |
| `gameVersion` | string | 清洗后的版本号（如 `1.5`） |
| `gameVersionReleaseDate` | string(date-time) | 版本发布日期 |
| `gameVersionTypeId` | int32 \| null | 游戏版本类型 ID |

### Pagination

| 字段 | 类型 | 说明 |
|------|------|------|
| `index` | int32 | 本次返回的起始索引（从 0 开始） |
| `pageSize` | int32 | 请求的页大小 |
| `resultCount` | int32 | 本次实际返回数量 |
| `totalCount` | int64 | 符合条件的总数量 |