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

2026-02-04 04:42:27作者：宣利权Counsellor

项目概述

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

技术架构

核心组件

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

数据流设计

客户端请求 → 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));

本地运行

克隆项目到本地
安装依赖：npm install
启动服务：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);
  });