Koneko_api_for_QZ-Music/Koneko_插件开发文档_v0.0.2.md

Koneko QZ Music v2/v3 插件开发文档

版本：0.0.2 | 作者：云汀(Miao-moe) | 整理日期：2026-06-20

---

一、概述

为 QZ Music v2/v3 编写 6 个音乐平台拓展插件：

• QQ音乐 (koneko_tx)
• 酷狗音乐 (koneko_kg)
• 酷我音乐 (koneko_kw)
• 网易云音乐 (koneko_wy)
• 咪咕音乐 (koneko_mg)
• GIT音源 (koneko_git)

二、插件规范

2.1 运行环境

• Node.js 运行时（Javet/V8）
• CommonJS 模块规范
• module.exports 导出接口
• 不支持 axios，使用内置 http/https 模块

2.2 ES5 兼容（Javet/V8 限制）

语法	状态	替代
let / const	❌	var
箭头函数	❌	function() {}
async/await	❌	Promise 链式
catch { } 无参数	❌	catch (e) { }
Promise.allSettled	❌	Promise.all + 手动包装
Object.entries/values	❌	for...in
Array.includes	❌	indexOf
String.startsWith	❌	indexOf(...) === 0
class	❌	对象字面量
模板字符串 ${}	✅	-
Buffer	✅	-

2.3 插件导出格式

module.exports = {
  musicSearch: { search: fn, tipSearch: fn, hotSearch: fn },
  tipSearch: { getList: fn },
  hotSearch: { getList: fn },
  getUrl: fn,
  getLyric: fn,
  songList: { getListDetail: fn },
  album: { getListDetail: fn },
  pluginInfo: { info, env, ext, quality, supportFunc },
  // 网易云特有
  userPlaylist: fn,
  dailyRecommend: fn,
  personalFm: fn,
  myLikedSongs: fn
}

2.4 搜索结果格式

{
  list: [{
    id: String,
    name: String,
    artists: String,   // 用 "、" 分隔
    source: String,    // tx/kg/kw/wy/mg
    pic: String,       // 封面大图
    mPic: String,      // 封面中图
    sPic: String,      // 封面小图
    albumName: String,
    albumId: String,
    interval: String,  // "m:ss"
    qualities: { standard: '3.21MB', exhigh: '7.85MB', ... }
  }],
  allPage: Number,
  limit: Number,
  total: Number,
  source: String
}

2.5 环境变量

通过 global.env 读取：

var env = global.env || {}
var CERU_KEY = env.ceru_key || ''
var WY_COOKIE = env.cookie || ''
var PLAYLIST_URL = env.playlist_url || ''

2.6 音质标识

ID	含义
standard	标准音质 (128k)
exhigh	高品音质 (320k)
lossless	无损音质 (FLAC)
hires	Hi-Res
jyeffect	高清环绕声
sky	沉浸环绕声
jymaster	超清母带

三、各平台 API

3.1 QQ音乐 (tx)

搜索签名: zzcSign = SHA1 + 自定义索引提取 + XOR 混淆 + base64

var PART_1_INDEXES = [23, 14, 6, 36, 16, 40, 7, 19]
var PART_2_INDEXES = [16, 1, 32, 12, 19, 27, 8, 5]
var SCRAMBLE_VALUES = [89, 39, 179, 150, 218, 82, 58, 252, 177, 52, 186, 123, 120, 64, 242, 133, 143, 161, 121, 179]

封面图规则：

• 有专辑ID：https://y.gtimg.cn/music/photo_new/T002R500x500M000{albumId}.jpg
• 无专辑ID：https://y.gtimg.cn/music/photo_new/T001R500x500M000{singerMid}.jpg

getUrl 音质参数：128k / 320k / 999k

3.2 酷狗音乐 (kg)

搜索接口：http://mobilecdn.kugou.com/api/v3/search/song

注意：返回字段是 errcode（不是 error_code）

封面图：搜索结果自带 imgurl，替换 {size} 为 400

3.3 酷我音乐 (kw)

搜索接口：http://search.kuwo.cn/r.s

封面图：https://img2.kuwo.cn/star/albumcover/300/{ALBUMID}.jpg

音质信息：在 N_MINFO 字段中解析

3.4 网易云音乐 (wy)

搜索接口：https://music.163.com/api/search/get/web（GET，不需要 weapi）

封面图：picId 需 Base64 编码

var picIdB64 = Buffer.from(String(s.album.picId)).toString('base64').replace(/=/g, '')
var pic = 'https://p2.music.126.net/' + picIdB64 + '/' + picIdStr + '.jpg'

加密接口：

• eapi：AES-128-ECB，key = e82ckenh8dichen8
• weapi：AES-128-CBC + RSA

Cookie 功能（需设置 cookie 环境变量）：

• userPlaylist() - 个人歌单（需 playlist_url）
• dailyRecommend() - 每日推荐
• personalFm() - 私人FM
• myLikedSongs() - 我喜欢的音乐
• songList(id) - 歌单详情
• album(id) - 专辑详情
• getLyric(id) - 歌词获取

3.5 咪咕音乐 (mg)

搜索签名：MD5 拼接

var sign = crypto.createHash('md5').update(
  str + signatureMd5 + 'yyapp2d16148780a1dcc7408e06336b98cfd50' + deviceId + time
).digest('hex')

封面图：搜索结果可能返回相对路径，需拼接 https://d.musicapp.migu.cn

3.6 GIT音源 (git)

纯音源插件，无搜索功能，仅 getUrl

四、getUrl 容灾机制

所有平台统一使用并发测速模式：

Promise.all(promises.map(function(p) {
  return p.then(function(v) { return { status: 'fulfilled', value: v } })
          .catch(function(e) { return { status: 'rejected', reason: e } })
})).then(function(results) {
  for (var i = 0; i < results.length; i++) {
    if (results[i].status === 'fulfilled') return results[i].value.url
  }
  return ''
})

音源 API 列表

API	平台	说明
聆澜	全部	需 ceru_key，最稳定
HUIBQ	全部	X-Request-Key: share-v3
星海	全部	聚合接口
念心	tx/kg/kw/mg	个人维护
长青	tx/kg/kw/mg	个人维护
星海备	全部	备用
fish	全部	个人维护
HYW	全部	需 X-Card-Key
忆音	tx	直接返回 URL
收集QQ	tx	QQ专用
收集KW	kw	酷我专用
bb	wy	网易云专用
ymc	wy	网易云专用
unms	wy	网易云专用
官方 weapi	wy	网易云官方

五、版本管理

• 所有平台统一版本号
• 当前版本：0.0.2
• 文件名格式：Koneko_{平台名}_v{版本号}.js

六、常见问题

问题	原因	解决
Cannot find module 'axios'	用了 axios	改用内置 http/https
Field 'list' is required	返回 songs 而非 list	改字段名为 list
搜索无结果	字段名不匹配	检查 errcode vs error_code
播放失败	mapBr 返回格式不对	tx/kg/kw/mg/git 用 320k，wy 用 320000
封面图不显示	URL 格式错误	检查各平台拼接规则

七、相关链接

• Gitea: http://171.80.3.149:4321/miao-moe
• CeruMusic: http://171.80.3.149:4321/miao-moe/CeruMusic
• QZMusic PC: http://171.80.3.149:4321/miao-moe/QZMusic_PC