QQMusicApi项目详解：打造你的专属QQ音乐API服务

项目概述

QQMusicApi是一个基于Node.js开发的API服务项目，它通过Express框架和Axios库实现了对QQ音乐官方接口的封装和增强。该项目为开发者提供了一个简单易用的方式来获取QQ音乐平台的各种数据，包括歌曲信息、歌单、排行榜、MV等内容。

技术架构

核心组件

1. Express框架：作为HTTP服务器基础，处理API请求和响应
2. Axios库：用于向QQ音乐官方接口发起HTTP请求
3. Cheerio：部分接口用于解析HTML内容
4. 数据缓存机制：优化接口响应速度

数据流设计

客户端请求 → Express路由 → 参数处理 → 调用QQ音乐官方API → 数据处理 → 返回客户端

安装与使用

通过NPM安装

npm install qq-music-api

基本使用示例

const qqMusic = require('qq-music-api');

// 设置用户Cookie（部分接口需要）
qqMusic.setCookie('your_cookie_here');

// 搜索歌曲示例
qqMusic.api('search', { key: '周杰伦' })
  .then(res => console.log(res))
  .catch(err => console.error(err));

本地运行

1. 克隆项目到本地
2. 安装依赖：npm install
3. 启动服务：npm start

默认服务端口为3300，可通过修改配置文件或设置环境变量PORT来更改。

核心功能解析

1. 音乐播放相关

获取播放链接

// 获取单个歌曲播放链接
qqMusic.api('song/url', { id: '0039MnYb0qxYhV' });

// 批量获取播放链接
qqMusic.api('song/urls', { id: '0039MnYb0qxYhV,004Z8Ihr0JIu5s' });

注意事项：

• 高品质音乐链接需要VIP账号的Cookie
• 部分数字专辑歌曲需要购买后才能获取播放链接

音质支持

格式	参数值	说明
MP3 128k	128	标准音质
MP3 320k	320	高品质
M4A	m4a	苹果格式
FLAC	flac	无损格式
APE	ape	无损格式

2. 搜索功能

综合搜索

// 搜索歌曲
qqMusic.api('search', {
  key: '关键词',
  t: 0, // 0:单曲 2:歌单 7:歌词 8:专辑 9:歌手 12:MV
  pageNo: 1,
  pageSize: 20
});

热搜词获取

qqMusic.api('search/hot')
  .then(res => console.log('当前热搜:', res.data));

3. 用户系统

Cookie管理

// 设置Cookie
qqMusic.setCookie('uin=123456; qm_keyst=xxx;');

// 获取当前Cookie
qqMusic.api('user/cookie');

// 刷新登录状态
qqMusic.api('user/refresh');

重要提示：Cookie信息涉及账号安全，请妥善保管，避免泄露。

4. 歌单操作

获取歌单详情

qqMusic.api('songlist', { id: '歌单ID' });

歌单分类

// 获取歌单分类
qqMusic.api('songlist/category');

// 按分类获取歌单
qqMusic.api('songlist/list', {
  category: '分类ID',
  sort: 5 // 5:推荐 2:最新
});

5. 歌曲信息

获取歌曲详情

qqMusic.api('song', { songmid: '歌曲MID' });

获取歌词

qqMusic.api('lyric', { songmid: '歌曲MID' });

返回的歌词和翻译都是Base64编码，客户端需要自行解码。

高级功能

1. 评论系统

// 获取评论
qqMusic.api('comment', {
  id: '资源ID',
  biztype: 1, // 1:歌曲 2:专辑 3:歌单 4:排行榜 5:MV
  type: 0 // 0:最新 1:热评
});

// 发表评论（需要登录）
qqMusic.api('comment/send', {
  id: '资源ID',
  biztype: 1,
  content: '评论内容'
}, 'POST');

2. MV相关

// 获取MV信息
qqMusic.api('mv', { id: 'MV的VID' });

// 获取MV播放链接
qqMusic.api('mv/url', { id: 'MV的VID' });

3. 排行榜

// 获取榜单列表
qqMusic.api('top/category', { showDetail: 1 });

// 获取榜单详情
qqMusic.api('top', { id: '榜单ID' });

最佳实践

错误处理

API返回的统一格式包含result字段：

• 100：成功
• 500：参数错误
• 400：未知异常
• 301：需要登录

建议在调用时做好错误处理：

qqMusic.api('some/api')
  .then(res => {
    if(res.result !== 100) {
      throw new Error(`API错误: ${res.result}`);
    }
    // 处理正常数据
  })
  .catch(err => {
    console.error('API调用失败:', err);
  });

性能优化

1. 对于高频调用的接口，建议在客户端实现缓存
2. 批量获取数据时尽量使用批量接口（如song/urls）
3. 合理设置pageSize减少请求次数

常见问题解答

Q：为什么获取不到音乐播放链接？

A：请检查：

1. 是否正确设置了VIP账号的Cookie
2. 歌曲是否为付费内容
3. Cookie是否已过期（可通过user/refresh刷新）

Q：如何获取无损音质的播放链接？

A：需要满足：

1. 使用VIP账号的Cookie
2. 歌曲本身有无损音源
3. 调用接口时指定type=flac或type=ape

Q：为什么部分接口返回301错误？

A：这些接口需要用户登录才能访问，请先设置有效的Cookie。

项目更新与维护

该项目持续更新，近期主要更新包括：

• 新增Jest测试框架支持
• 修复专辑信息获取问题
• 支持MV点赞功能
• 优化NPM使用体验

建议开发者定期关注项目更新，以获取最新功能和修复。

法律与版权声明

本项目仅供学习和技术研究使用，请勿用于商业用途。所有音乐版权归QQ音乐及其相关权利方所有。使用本项目时，请遵守相关法律法规，尊重版权。

通过QQMusicApi，开发者可以快速构建基于QQ音乐数据的个性化应用，但请合理使用API，避免对官方服务器造成过大压力。