KugouMusicAPI

项目简介

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

Important

注意

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

快速开始

环境要求

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

安装

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

配置

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

cp .env.example .env

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

启动服务

# 默认端口 9191
npm start

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

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

重要提示

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

在线体验与文档

• 在线文档 - 启动服务后访问
• GitHub 仓库

常见部署方式

1. 本地部署

npm install
npm start

2. PM2 部署

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

3. Docker 部署

# 构建镜像
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. 搜索歌曲

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

参数：

• keyword - 搜索关键词（必填）
• page - 页码，默认 1

响应示例：

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

2. 获取播放地址

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

参数：

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

响应示例：

{
  "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. 获取歌词

GET /api/lyric?hash=D1D7835F9BED257E613A2C854333667B

参数：

• hash - 歌曲 hash（必填）

响应示例：

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

4. 获取音质信息

GET /api/audio_info?mixSongId=123456789

参数：

• mixSongId - 歌曲 MixSongID（必填）

响应示例：

{
  "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 项目中引入和调用：

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();

单元测试

npm test

主要功能特性

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

调用前须知

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

贡献与社区

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

致谢

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

License

MIT License

---

_{Built with Node.js for developers}