QQ Music API

🍴 本项目 Fork 自 Rain120/qq-music-api，原项目已停止维护，此版本持续更新中
基于 Koa 2 与 TypeScript 的 QQ 音乐 API 服务，包含扫码登录、用户头像、MV 播放地址、批量接口等能力。
当前代码仅供学习与研究使用，不可做商业用途。

从 2.3.0 开始，新版本会持续减少 npm 包安装时的依赖体积，推荐新项目和升级用户优先使用 2.3 及之后版本。

项目概览

• 运行时：Node.js 20+
• 服务框架：Koa 2
• 开发语言：TypeScript
• 路由系统：@koa/router
• 文档系统：VitePress 2
• 测试框架：Vitest
• 默认端口：3200

API 结构图

当前版本已包含扫码登录相关接口，并已完成 TypeScript 迁移。

📖 详细 API 文档： 查看完整 API 文档

环境要求

本项目基于 Koa 2 + TypeScript，需要 Node.js 20.0.0+。

node -v

安装

方式一：克隆仓库

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

方式二：NPM 安装

npm install @sansenjian/qq-music-api

NPM 包默认包含运行所需的 dist/、本地交互测试页 public/，以及已构建的文档站点 docs-dist/。如果你只想在自己的发布产物中保留 API 运行时，可以在你的项目打包配置中自行排除 node_modules/@sansenjian/qq-music-api/docs-dist/ 或 node_modules/@sansenjian/qq-music-api/public/。

在项目中使用：

const { spawn } = require('child_process');
const path = require('path');

const qqMusicPath = path.join(__dirname, 'node_modules', '@sansenjian/qq-music-api', 'dist', 'app.js');

spawn('node', [qqMusicPath], {
	env: { ...process.env, PORT: '3200' },
	stdio: 'inherit',
});

项目启动

# 开发模式
npm run dev

# 生产构建
npm run build

# 生产运行
npm run start

# 运行测试
npm run test

# 启动文档站点
npm run docs:dev

项目默认监听端口为 3200。

依赖版本说明（同步 package.json）

生产依赖

依赖	说明
@koa/router	路由
axios	HTTP 客户端
koa	Web 框架

开发依赖

依赖	说明
oxlint	代码检查（替换 ESLint）
oxc-transform	Rust TypeScript 转译
typescript	类型检查 + 声明生成
vite	打包工具（Rolldown）
vitest	测试框架
tsx	开发热重载
prettier	代码格式化
@commitlint/*	提交规范
husky + lint-staged	Git hooks
vitepress + vue	文档站点
sinon	测试 mock
supertest	HTTP 测试

当前主要能力

音乐与播放

• 歌曲播放链接
• 歌曲与专辑图片
• 歌词与翻译歌词
• MV 播放信息

歌手与歌单

• 歌手热门歌曲、资料、相似歌手、关注数
• 歌手 MV 与歌手专辑
• 歌单分类、歌单列表、歌单详情
• 排行榜列表与详情

用户与登录

• 用户头像
• 用户歌单
• QQ 扫码登录
• Cookie / 登录态相关接口

其他能力

• 评论信息
• 数字专辑
• 电台列表
• 首页推荐
• 下载地址
• 票务信息

文档入口

• 用户接口说明：docs/api/user.md
• 其他接口说明：docs/api/other.md
• API 调试台：docs/api/playground.md
• 用户歌单测试说明：docs/TEST_USER_PLAYLISTS.md
• 在线文档主页： https://sansenjian.github.io/qq-music-api/

关于项目

灵感来源

• Binaryify/NeteaseCloudMusicApi
• Vue2.0 开发企业级移动端音乐 Web App

参考内容

• Koa 2
• Axios
• 阮一峰老师 - HTTP Referer 教程

当前限制

1. 部分用户能力仍依赖有效 Cookie。
2. 上游 QQ 音乐接口字段可能变更，个别接口需要持续跟踪。
3. 用户歌单接口仍在持续验证与调整中，详见 docs/TEST_USER_PLAYLISTS.md。

贡献

We welcome all contributions. You can submit any ideas as pull requests or as GitHub issues.

维护者

• GitHub

原作者

本项目基于 Rain120 的开源项目，感谢原作者的贡献。

• GitHub
• 知乎
• 掘金

License

MIT

Copyright © 2019-present Rain120.
Fork maintained by sansenjian.