KuGou

KO | EN

gitlite — search

#ai #llm #android #machine-learning #rust #linux #macos #nodejs #java #awesome #cli #vue #awesome-list #ios

(★ 30)

酷狗音乐第三方 Node.js API，支持歌曲搜索、播放链接获取、歌词获取等功能，适合自建服务、二次开发和多平台部署。

KuGou 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">KugouMusicAPI</h1>

## 项目简介

酷狗音乐第三方 Node.js API，支持歌曲搜索、播放链接获取、歌词获取等功能，适合自建服务、二次开发和多平台部署。

> [!IMPORTANT]
> 
> ## 注意
> 
> - 本项目是一个第三方 API，仅供学习交流使用。
> - 使用本项目时请务必遵守相关法律法规，遵守 `MIT` 协议，尊重酷狗音乐的服务条款。
> - 请勿用于商业用途，如有侵权请联系删除。
> - 感谢尊重和理解！

## 快速开始

### 环境要求

- Node.js 18 及以上
- 推荐使用 npm 或 yarn 进行依赖管理

### 安装

```bash
git clone https://github.com/Yu9191/KuGou.git
cd KuGou
npm install
```

### 配置

复制环境变量模板并配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入必要的配置参数（TOKEN、MID、USERID 等）。

### 启动服务

```bash
# 默认端口 9191
npm start

# 指定端口（如 4000）
PORT=4000 npm start

# 开发模式（自动重启）
npm run dev
```

### 重要提示

- 调用前请务必阅读文档的 [调用前须知](#调用前须知) 部分。
- 推荐将敏感信息（如 TOKEN）通过环境变量进行配置。
- 部分参数需要定期更新以保证服务正常运行。

## 在线体验与文档

- [在线文档](http://localhost:9191) - 启动服务后访问
- [GitHub 仓库](https://github.com/Yu9191/KuGou)

## 常见部署方式

### 1. 本地部署

```bash
npm install
npm start
```

### 2. PM2 部署

```bash
npm install -g pm2
pm2 start app.js --name kugou-api
pm2 startup
pm2 save
```

### 3. Docker 部署

```bash
# 构建镜像
docker build -t kugou-api .

# 运行容器
docker run -d -p 9191:9191 --name kugou-api kugou-api

# 使用 docker-compose
docker-compose up -d
```

### 4. 环境变量配置

| 变量名                        | 默认值                                  | 说明                                                 |
|----------------------------|--------------------------------------|----------------------------------------------------| 
| **PORT**                   | `9191`                               | 服务端口                                               |
| **CORS_ALLOW_ORIGIN**      | `*`                                  | 允许跨域请求的域名。若需要限制，请指定具体域名（例如 `https://example.com`）。 |
| **APPID**                  | `1000`                               | 酷狗应用 ID                                            |
| **CLIENTVER**              | `20549`                              | 客户端版本                                              |
| **USERID**                 | 必填                                   | 用户 ID（需要定期更新）                                      |
| **MID**                    | 必填                                   | 设备 MID（需要定期更新）                                     |
| **TOKEN**                  | 必填                                   | 访问令牌（需要定期更新）                                       |
| **KG_RF**                  | 必填                                   | 请求指纹（需要定期更新）                                       |
| **KG_DEVID**               | 必填                                   | 设备ID（需要定期更新）                                       |

## 配置参数获取方法

> **重要提示：需要酷狗会员账号的Cookie才能获取高音质播放链接**

### 获取步骤：

1. **准备工具**：下载抓包工具（如 Charles、Fiddler、Burp Suite 等）
2. **开启抓包**：启动抓包工具并开始监听网络请求
3. **播放歌曲**：在酷狗音乐客户端播放任意一首歌曲
4. **搜索请求**：在抓包工具中搜索URL关键词 `tracker` 或 `v5/url`
5. **提取参数**：找到播放地址请求，对照请求头参数填写到 `.env` 文件中

### 主要参数对应关系：

```
请求头中的参数 → .env 文件中的变量
KG-RF → KG_RF
KG-FAKE → KG_FAKE  
KG-DEVID → KG_DEVID
Cookie中的KugooID → USERID
Cookie中的kg_mid → MID
URL参数中的token → TOKEN
```

## 关于签名算法 (Signature Algorithm)

项目已同步更新支持 **2026.04.02** 最新版酷狗音乐 (V5/URL) 签名算法。

### 签名生成步骤：

1.  **参数收集**：包含请求 URL 中的所有 Query 参数（如 `hash`, `appid`, `clienttime`, `mid`, `token` 等）。
2.  **字典排序**：将所有参数按参数名（Key）进行 **字母升序排序** (A-Z)。
3.  **字符串拼接**：
    *   按照排序后的顺序，将参数拼接为 `key1=value1key2=value2...keyn=valuen` 的格式。
    *   **重要提示**：拼接过程中 **不使用** `&` 符号。
4.  **两端加盐**：
    *   在拼接后的字符串最前面和最后面分别加上签名盐值（Salt）。
    *   格式：`[SALT] + [拼接后的字符串] + [SALT]`
5.  **MD5 计算**：对最终生成的字符串进行 MD5 加密（32位小写），结果即为 `signature` 参数。

> [!TIP]
> 正确的签名对于 `v5/url` 解析至关重要。如果返回 `status: 0` 或签名错误，请检查 `SALT_SIGN` 配置以及参数拼接顺序是否严格遵循上述逻辑。

### 风控说明

⚠️ **当前存在风控机制**：
- 大概1-2天会触发一次人机验证
- 暂时没有自动化解决方案
- 触发验证后需要重新获取参数
- 欢迎贡献解决方案，提交PR！

### 服务器环境特别说明

🔧 **服务器部署重要提示**：
- 海外服务器可能遇到搜索接口返回空结果的问题
- 这是由于酷狗API的地域限制导致的
- **解决方案**：在 `.env` 文件中配置 `FAKE_IP` 为国内IP地址
- 例如：`FAKE_IP=你的酷狗账号登录的国内IP地址`
- 配置后代码会自动添加必要的请求头解决此问题

## API 接口文档

### 1. 搜索歌曲

```http
GET /api/search?keyword=周杰伦&page=1
```

**参数：**
- `keyword` - 搜索关键词（必填）
- `page` - 页码，默认 1

**响应示例：**
```json
{
  "ok": true,
  "total": 1000,
  "songs": [
    {
      "fileName": "稻香",
      "singerName": "周杰伦",
      "albumName": "魔杰座",
      "hash": "D1D7835F9BED257E613A2C854333667B",
      "mixSongId": "123456789",
      "albumId": "966846",
      "duration": 223,
      "fileSize": 8945234,
      "extName": "mp3"
    }
  ]
}
```

### 2. 获取播放地址

```http
GET /api/v5url?hash=D1D7835F9BED257E613A2C854333667B&mode=lite
```

**参数：**
- `hash` - 歌曲 hash（必填）
- `quality` - 音质：high/320/128，默认 high
- `fallback` - 自动降级：1/0，默认 1
- `mode` - 输出模式：lite/full，默认 lite

**响应示例：**
```json
{
  "ok": true,
  "hash": "D1D7835F9BED257E613A2C854333667B",
  "quality": "high",
  "extName": "mp3",
  "fileSizeText": "8.53 MB",
  "timeLengthText": "3:43",
  "language": "国语",
  "cover": "https://imge.kugou.com/stdmusic/480/20190101/123456.jpg",
  "primaryUrl": "https://fs.kugou.com/202501/abc123.mp3",
  "urls": [
    "https://fs.kugou.com/202501/abc123.mp3",
    "https://backup.kugou.com/202501/abc123.mp3"
  ]
}
```

### 3. 获取歌词

```http
GET /api/lyric?hash=D1D7835F9BED257E613A2C854333667B
```

**参数：**
- `hash` - 歌曲 hash（必填）

**响应示例：**
```json
{
  "ok": true,
  "id": "123456",
  "accesskey": "abc123",
  "content": "[00:00.00]稻香 - 周杰伦\n[00:15.00]对这个世界如果你有太多的抱怨\n...",
  "fmt": "lrc"
}
```

### 4. 获取音质信息

```http
GET /api/audio_info?mixSongId=123456789
```

**参数：**
- `mixSongId` - 歌曲 MixSongID（必填）

**响应示例：**
```json
{
  "ok": true,
  "songName": "稻香",
  "singerName": "周杰伦",
  "albumName": "魔杰座",
  "albumId": "966846",
  "qualities": [
    {
      "name": "flac",
      "hash": "ABC123",
      "fileSize": 25600000,
      "bitrate": 1411
    },
    {
      "name": "320",
      "hash": "DEF456",
      "fileSize": 8960000,
      "bitrate": 320
    }
  ]
}
```

## Node.js 方式调用

支持直接在 Node.js 项目中引入和调用：

```js
import { searchSong, fetchOnce, getLyric } from './src/api/search.js';
import { getConfig } from './src/config.js';

async function main() {
  const config = getConfig();
  
  // 搜索歌曲
  const searchResult = await searchSong(config, '周杰伦', 1);
  console.log(searchResult);
  
  // 获取歌词
  const lyricResult = await getLyric(config, 'D1D7835F9BED257E613A2C854333667B');
  console.log(lyricResult);
}

main();
```

## 单元测试

```bash
npm test
```

## 主要功能特性

- 歌曲搜索 - 支持关键词搜索，返回详细歌曲信息
- 播放地址获取 - 支持多种音质，自动降级
- 歌词获取 - 支持 LRC 格式歌词
- 音质信息 - 获取歌曲所有可用音质
- 高性能 - 基于 Express.js，支持高并发
- 易部署 - 支持 Docker、PM2 等多种部署方式
- 跨域支持 - 内置 CORS 支持

## 调用前须知

1. **请求频率限制**：建议控制请求频率，避免对服务器造成压力
2. **参数有效性**：部分参数（如 TOKEN、MID）需要定期更新
3. **错误处理**：请妥善处理 API 返回的错误信息
4. **合法使用**：仅供学习交流使用，请勿用于商业用途
5. **配置要求**：必须正确配置环境变量才能正常使用

## 贡献与社区

- 欢迎提交 PR、Issue 参与维护
- 如有问题请在 GitHub Issues 中反馈

## 致谢

感谢酷狗音乐提供的优质音乐服务，本项目仅用于技术学习交流。

## License

[MIT License](LICENSE)

---

<p align="center">
  <sub>Built with Node.js for developers</sub>
</p>

KuGou

KuGou 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

KuGou

KuGou 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README