QQ音乐API接口服务：从部署到调用的完整指南

一、认识QQ音乐API项目

什么是QQ音乐API？

这是一个基于 Koa 2 + TypeScript 开发的开源接口服务（项目标识：qq-music-api），能够帮助开发者轻松获取QQ音乐平台的各类数据，包括歌曲播放链接、歌词、歌手信息、专辑详情等。项目采用模块化架构设计，所有功能通过HTTP接口形式提供，特别适合学习Node.js后端开发或构建音乐相关应用的开发者使用。

核心功能亮点 ✨

• 提供音乐播放、歌词获取、歌手信息查询等 30+ 实用接口
• 基于 Koa 2 的轻量级架构，性能高效且易于扩展
• 完整的请求/响应处理流程，包含错误处理和数据格式化
• 支持本地部署、NPM包安装和函数式调用三种使用方式
• 包含 MCP（Model Context Protocol）能力，支持 AI Agent 集成
• 完整的单元测试和集成测试覆盖

---

二、环境准备与项目下载

2.1 必备开发环境

在开始前，请确保你的电脑已安装以下工具：

• Node.js：运行JavaScript的服务器环境，本项目要求 v20.17.0 或 >= 22.9.0
  → 检查方法：打开终端输入 node -v，出现类似 v20.17.0 的版本号即表示已安装

• npm：Node.js自带的包管理工具，用于安装项目依赖（要求 ^11.0.0）
  → 检查方法：终端输入 npm -v，出现版本号即正常（通常随Node.js自动安装）

2.2 获取项目源代码

方式一：通过 Git 克隆（推荐用于开发）

git clone git@github.com:sansenjian/qq-music-api.git
cd qq-music-api

方式二：直接下载 ZIP 压缩包

访问项目仓库：https://github.com/sansenjian/qq-music-api，点击 “Code” → “Download ZIP”

方式三：NPM 安装（推荐用于生产）

npm install @sansenjian/qq-music-api

---

三、项目部署与启动指南

3.1 安装依赖包

项目运行前需要安装所有依赖的第三方库，执行以下命令：

npm install

该命令会读取 package.json 文件，自动下载并安装所有必要依赖，完成后会生成 node_modules 文件夹

3.2 启动服务的三种方式

根据不同使用场景，提供三种启动方式：

方式一：常规启动（适合生产环境）

npm run build
npm run start

执行后会运行编译后的代码，启动服务器并监听 3200 端口，终端会显示服务启动成功的提示信息

方式二：开发模式启动（适合代码调试）

npm run dev

该命令使用 tsx 实时编译 TypeScript，监听文件变化，代码修改后会自动热更新，适合开发过程中使用

方式三：作为库函数调用（无需启动HTTP服务）

import { search, getMusicPlay, getLyric } from '@sansenjian/qq-music-api/sdk';

const searchResult = await search({ key: '周杰伦', limit: 20 });
const playResult = await getMusicPlay({
  songmid: '003rJSwm3TechU',
  quality: '320',
  cookie: 'uin=o123456; qqmusic_key=your-key',
});
const lyricResult = await getLyric({
  songmid: '003rJSwm3TechU',
  isFormat: true,
});

3.3 验证服务是否正常运行

服务启动成功后，打开浏览器访问以下地址：

http://localhost:3200

如果看到 API 文档页面或测试页面，即表示服务已成功运行。

---

四、项目结构与核心文件解析

4.1 目录结构概览

项目采用清晰的模块化组织方式，主要目录功能如下：

qq-music-api/
├── src/                    # 源代码目录
│   ├── app.ts              # 应用入口文件
│   ├── koaApp.ts           # Koa 应用配置
│   ├── server.ts           # 服务器启动逻辑
│   ├── cli.ts              # 命令行接口
│   ├── config/             # 配置文件目录
│   │   ├── service-config.ts    # 服务配置
│   │   ├── user-info.ts         # 用户信息配置
│   │   └── user-info-store.ts   # 用户信息存储
│   ├── controllers/        # 控制器层（处理HTTP请求）
│   │   ├── getMusicPlay.ts      # 歌曲播放接口
│   │   ├── getLyric.ts          # 歌词接口
│   │   ├── getSearchByKey.ts    # 搜索接口
│   │   └── ...
│   ├── services/           # 服务层（核心业务逻辑）
│   │   └── apis/            # QQ音乐API封装
│   ├── routes/             # 路由配置
│   │   ├── router.ts           # 路由注册
│   │   └── api-metadata.ts     # API元数据定义
│   ├── middlewares/        # 中间件
│   │   ├── koa-cors.ts         # CORS跨域处理
│   │   ├── body-parser.ts      # 请求体解析
│   │   └── security-headers.ts # 安全响应头
│   ├── util/               # 工具函数
│   │   ├── request.ts          # HTTP请求封装
│   │   ├── cookie.ts           # Cookie处理
│   │   └── logger.ts           # 日志工具
│   └── types/              # TypeScript类型定义
├── tests/                  # 测试文件
├── docs/                   # 文档站点
├── public/                 # 静态资源
├── packages/mcp/           # MCP Server 包
├── package.json            # 项目配置
├── vite.config.ts          # Vite配置
└── tsconfig.json           # TypeScript配置

4.2 关键文件功能解析

文件路径	功能说明
src/app.ts	应用入口，判断运行模式并启动服务器
src/koaApp.ts	Koa应用核心配置，注册中间件和路由
src/server.ts	HTTP服务器启动逻辑，处理端口监听
src/routes/router.ts	路由注册中心，动态加载API元数据
src/routes/api-metadata.ts	API接口元数据定义（路径、方法、控制器映射）
src/controllers/	控制器层，处理HTTP请求并调用服务
src/services/apis/	服务层，封装QQ音乐原始API调用
src/util/request.ts	统一的HTTP请求封装，处理Cookie和请求头

---

五、常用API接口调用示例

5.1 获取歌曲播放链接

请求示例：

GET http://localhost:3200/api/song/url?id=003rJSwm3TechU

参数说明：

参数	类型	必填	说明
id	string	是	歌曲ID（songmid）
quality	string	否	音质：128 / 320 / flac，默认 128

响应示例：

{
  "code": 200,
  "data": {
    "url": "http://xxx.qqmusic.qq.com/xxx.mp3",
    "quality": "128k",
    "type": "mp3",
    "songmid": "003rJSwm3TechU"
  }
}

5.2 获取歌词信息

请求示例：

GET http://localhost:3200/api/lyric?id=003rJSwm3TechU

参数说明：

参数	类型	必填	说明
id	string	是	歌曲ID（songmid）
isFormat	boolean	否	是否格式化，默认 false

响应示例：

{
  "code": 200,
  "lrc": {
    "version": 11,
    "lyric": "[00:01.23]歌曲名\n[00:05.67]演唱：歌手名\n..."
  },
  "tlyric": {
    "lyric": "[00:01.23]Song Title\n[00:05.67]Singer: Artist Name\n..."
  }
}

5.3 搜索歌曲

请求示例：

GET http://localhost:3200/api/search?key=周杰伦&limit=10

参数说明：

参数	类型	必填	说明
key	string	是	搜索关键词
limit	number	否	返回数量，默认 20
offset	number	否	偏移量，默认 0
type	number	否	搜索类型，默认 0（综合）

响应示例：

{
  "code": 200,
  "data": {
    "song": {
      "list": [
        {
          "songmid": "003rJSwm3TechU",
          "songname": "晴天",
          "singer": [{"name": "周杰伦"}],
          "albumname": "叶惠美"
        }
      ]
    }
  }
}

5.4 获取歌单详情

请求示例：

GET http://localhost:3200/api/playlist/detail?id=3102963639

参数说明：

参数	类型	必填	说明
id	string	是	歌单ID

5.5 获取排行榜

请求示例：

GET http://localhost:3200/api/top/list

响应示例：

{
  "code": 200,
  "data": [
    {
      "id": "26",
      "name": "飙升榜",
      "picUrl": "https://y.gtimg.cn/music/photo_new/T003R300x300M0000026..."
    }
  ]
}

---

六、开发与扩展建议

6.1 代码修改与调试

如果需要修改或扩展功能，建议按以下步骤进行：

1. 使用开发模式启动：npm run dev 会自动监听文件变化并热更新

2. 修改对应模块：

   • 新增接口：在 src/controllers/ 添加控制器，在 src/services/apis/ 添加服务逻辑
   • 注册路由：在 src/routes/api-metadata.ts 中添加API元数据

3. 测试接口调用：使用浏览器、Postman或curl直接访问接口URL验证效果

6.2 项目配置优化

• 端口修改：默认端口 3200，可通过环境变量 PORT 或修改 src/server.ts 调整

• 跨域设置：CORS配置位于 src/middlewares/koa-cors.ts，可根据需求修改 origin 参数

• 请求超时：可在 src/util/request.ts 中调整API请求的超时时间

6.3 MCP Server 开发

项目支持 MCP（Model Context Protocol）能力，可通过以下命令启动：

npm run mcp:dev

MCP Server 提供以下工具：

• qq_music_search_songs - 搜索歌曲
• qq_music_get_top_lists - 获取排行榜
• qq_music_get_playlist_detail - 获取歌单详情
• qq_music_auth_status - 登录状态查询

---

七、常见问题解决

7.1 服务启动失败

端口被占用：错误信息包含 "EADDRINUSE: address already in use :::3200"
→ 解决：关闭占用3200端口的程序，或设置环境变量 PORT=3201 修改端口

依赖安装不完整：错误信息包含 "Cannot find module 'xxx'"
→ 解决：重新执行 npm install，确保网络通畅

Node.js版本过低：错误信息包含版本不兼容提示
→ 解决：升级 Node.js 到 20.17.0+ 版本

7.2 接口返回404或500错误

404错误：请求的接口路径不正确
→ 检查：确认URL路径与 src/routes/api-metadata.ts 中的路由配置一致

500错误：服务器内部处理出错
→ 检查：查看终端输出的错误日志，通常会显示具体的错误位置和原因

7.3 接口返回数据为空或异常

Cookie失效：部分接口需要有效Cookie才能返回数据
→ 解决：参考项目文档配置Cookie，或使用登录接口获取有效登录态

上游接口变更：QQ音乐官方接口字段可能变更
→ 解决：更新 src/services/apis/ 中的API封装逻辑

---

八、项目扩展与学习建议

如何进一步学习和使用该项目？

1. 阅读源代码：重点理解 src/services/apis/ 目录下的接口实现，学习如何构造请求和解析响应

2. 尝试二次开发：添加新的API接口，如"获取用户歌单"或"推荐歌曲列表"

3. 结合前端框架：使用 React/Vue/Angular 等框架构建音乐播放器界面，调用本地API服务

4. 学习Koa2框架：通过该项目了解中间件机制、路由处理、异步编程等后端开发概念

5. 参与开源贡献：提交Issue反馈问题，或提交PR贡献代码

---

九、项目资源

• 项目仓库：https://github.com/sansenjian/qq-music-api
• 在线文档：https://sansenjian.github.io/qq-music-api/
• API调试台：http://localhost:3200/playground
• NPM包：https://www.npmjs.com/package/@sansenjian/qq-music-api

---

⚠️ 重要提示：本项目仅供学习交流使用，请勿用于商业用途，遵守QQ音乐平台的使用规范和相关法律法规。

---

通过本指南，你已经掌握了QQ音乐API项目的部署、配置和基本使用方法。该项目不仅提供了实用的音乐数据接口，更是学习Node.js后端开发的良好范例，建议在此基础上进行更多实践和探索。