QQ 音乐 API，基于
Koa2 + TypeScript构建，通过 Web 端请求 QQ 音乐接口数据。本项目集成了自动化数据处理代理，提供高效、易用的接口服务。 有问题请提 issue。欢迎阅读 参与贡献指南 参与项目开发，并查阅 AI 代理指南 了解自动化机制。 当前主干分支已完成 TypeScript 化改造，核心源码、测试与构建链路均已切换到 TypeScript 体系。 TypeScript 版本请使用next分支，JavaScript 版本请使用main分支。
⚠️ 当前代码仅供学习，不可做商业用途。
目前暂时没有时间做登录模块的接口，欢迎各位大佬给我
PR, 阿里嘎多
本项目采用
Koa2 + TypeScript技术栈，建议使用较新的 Node.js LTS 版本进行开发与运行。
node -v
请确保您的本地 Node.js 版本满足 环境要求。
git clone git@github.com:Rain120/qq-music-api.git
cd qq-music-api
npm install# 开发环境（支持热重载）
npm run dev
# 类型检查
npm run build
# 代码检查
npm run lint
# 单元测试
npm run test
# 本地启动
npm start项目默认监听端口是 3200，启动成功后可在浏览器访问 http://localhost:3200 体验接口服务。
- 应用入口：
src/app.ts负责启动Koa、注册中间件、挂载路由，并暴露/explorer、/explorer/index.html、/explorer/metadata。 - 控制器层：
src/controllers/*负责处理 HTTP 入参、调用服务层并整理返回结果。 - 服务层：
src/services/*负责访问 QQ 音乐相关能力，是歌曲、歌手、歌单、排行榜等数据获取逻辑的核心承载层。 - Explorer 元数据层：
src/config/apiExplorer.ts维护接口清单、请求方法、分类、参数与POST请求体示例，驱动调试表单动态渲染。 - Explorer 逻辑层：
src/explorer/contracts、src/explorer/domain、src/explorer/application负责状态模型、树构建、搜索筛选和 Store/Command 逻辑。 - Explorer 视图层：
public/explorer/*提供静态页面、交互脚本和样式，组成完整的本地调试工作台。 - 测试与文档：
tests/*覆盖控制器、服务和 Explorer，docs/*用于 Docsify 文档与界面截图展示。
API Explorer是项目内置的本地接口调试工作台，用于快速选择接口、填写参数、发送请求并查看结果。- 默认入口地址是
http://localhost:3200/explorer，访问/explorer时会自动重定向到/explorer/index.html。 - Explorer 元数据接口为
http://localhost:3200/explorer/metadata，页面会基于该接口动态生成可调试的接口列表与表单。
# 开发模式：默认自动打开 Explorer
npm run dev
# 本地启动服务后手动打开 Explorer
npm start
# 启动时显式开启自动打开
AUTO_OPEN_EXPLORER=true npm start
# 禁用自动打开（dev 脚本默认会开启）
AUTO_OPEN_EXPLORER=false npm run devnpm run dev默认会设置AUTO_OPEN_EXPLORER=true，因此服务启动后会自动拉起浏览器。npm start默认只启动服务，不会自动打开页面，可手动访问http://localhost:3200/explorer。- 在
CI或测试环境下不会自动打开浏览器。
- 启动服务并打开
http://localhost:3200/explorer。 - 在顶部选择请求方法：
ALL、GET或POST。 - 在搜索框中输入接口名、路由关键字或分类关键字，选择目标接口。
- 根据表单提示填写路径参数、查询参数，或为
POST接口编辑 JSON Body。 - 点击
发送请求，在右侧查看最新响应结果。 - 在
Logs区域检索当前会话中的历史请求、失败记录和最近一次请求。
- 接口筛选：支持按请求方法过滤，并通过搜索框快速定位接口。
- 动态表单：根据接口元数据自动生成路径参数、查询参数和请求体输入区域。
- 响应预览：展示最近一次请求的状态、耗时和格式化后的返回内容。
- 会话日志：保存当前页面会话内的请求记录，支持按关键字搜索以及按
全部、仅失败、仅进行中、仅成功过滤。 - 快速跳转：内置
最近请求和最近失败快捷按钮，便于定位调试问题。
整体预览
以搜索歌曲接口为例：
- 启动项目后进入
http://localhost:3200/explorer。 - 选择或搜索
getSearchByKey。 - 在参数区填写
key=周杰伦，可按需补充limit、page等参数。 - 点击
发送请求。 - 在
Response面板查看接口返回，在Logs面板查看本次请求的 URL、状态和结果摘要。
提示：部分
POST接口会提供默认 JSON Body 示例，可直接修改后发起请求，适合调试批量查询类接口。
- 服务框架：
Koa2 - 语言体系：
TypeScript - 请求能力：
Axios - 代码检查：
Biome - 测试方案：
Jest + Supertest - 构建与容器：支持本地运行与 Docker 镜像构建
- 持续补齐接口层、服务层与工具层测试用例，进一步提升覆盖率与回归稳定性。
- 完善 TypeScript 类型建模，收敛控制器、服务返回结构与公共工具的类型边界。
- 优化 Docker 与生产部署链路，确保构建产物、运行方式和发布流程保持一致。
- 持续更新接口文档、贡献指南和 AI 代理说明，减少文档与实现之间的偏差。
- 逐步推进登录态、个性化数据等高复杂度接口能力的调研与实现。
# local local build
npm run build:local-images
# local remote build
npm run build:remote-images
# build images
npm run build:images
# local run
npm run run:images
# remote run
docker pull qq-music-api- 获取歌曲播放链接 2021-01-24
- 支持自定义设置
cookie2021-01-23 - 获取歌曲 + 专辑图片 2020-05-24
- 获取歌手热门歌曲 2020-07-04
- 获取QQ音乐产品的下载地址
- 获取歌单分类
- 获取歌单列表
- 获取歌单详情
- 获取MV标签
- 获取MV播放信息
- 获取歌手MV
- 获取相似歌手
- 获取歌手信息
- 获取歌手被关注数量信息
- 获取电台列表
- 获取专辑
- 获取数字专辑
- 获取歌曲歌词
- 获取MV
- 获取新碟信息
- 获取歌手专辑
-
获取歌曲VKey2021-01-24 - 获取搜索热词
- 获取关键字搜索提示
- 获取搜索结果
- 获取首页推荐
- 获取排行榜单列表
- 获取排行榜单详情
- 获取评论信息(cmd代表的意思没太弄明白)
- 获取票务信息
- 获取歌单详情
- 获取歌手列表
使用apis详见文档
灵感来自
Binaryify/NeteaseCloudMusicApi
参考内容
- 当前已补充基础
unit test与接口测试，但整体覆盖率和复杂场景用例仍有继续提升空间。 - 登录、获取个人信息等依赖登录态的接口能力仍未完善。
本项目引入了智能化代理架构以优化数据获取和解析链路。详细了解各 AI 代理的角色、功能以及调用规范，请查阅我们的 AI 代理指南 (AGENTS.md)。
我们非常欢迎并感激所有的贡献！无论是提交 Bug、改进文档还是新增功能，您的支持对项目发展至关重要。
详细的贡献流程、代码提交规范以及本地开发配置，请仔细阅读我们的 参与贡献指南 (CONTRIBUTING.md)。您可以通过提交 Pull Requests 或发布 Issue 来参与共建。
Front-End development engineer, technology stack: React + Typescript + Mobx, also used Vue + Vuex for a while
Copyright © 2019-present Rain120.