miao-moe/Koneko_api_for_QZ-Music

Fork 0

Files

miao-moe c6eeb253d0 Update to v0.0.4: add aggregated plugins with API failover, update docs

2026-06-20 12:31:39 +08:00

10 KiB

Raw Blame History

Koneko QZ Music v2 插件开发避坑指南

版本: 0.0.3 | 作者: 云汀(Miao-moe) | 目标: 支持到别的 AI 继续开发

一、项目背景

QZ Music v2 是一款 Android 音乐播放器，支持通过拓展插件接入多平台音源。插件系统基于 Node.js 运行时（Javet/V8），每个插件是一个单独的 .js 文件，通过 module.exports 导出接口。

1.1 插件加载机制

canary 12-4 版本之前：直接加载 .js 文件
canary 12-4 及之后：需要 文件夹 + plugin.json + index.js 结构（但用户要求只用 .js，所以当前版本是单文件）
运行时环境变量通过 global.env 访问，不是 process.env

1.2 插件导出格式

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

二、Javet/V8 兼容性大坑（最重要）

QZ Music 使用 Javet 作为 JS 运行时（基于 V8），不支持现代 ES 语法，必须用保守写法：

语法	是否支持	正确写法
`let` / `const`	❌	`var`
箭头函数 `() => {}`	❌	`function() {}`
`async` / `await`	❌	`Promise` 链式调用
`catch { }`（无参数）	❌	`catch (e) { }`
`Promise.allSettled`	❌	`Promise.all` + 手动包装
`Object.entries` / `Object.values`	❌	`for...in` 遍历
`Array.prototype.includes`	❌	`indexOf(...) !== -1`
`String.prototype.startsWith`	❌	`indexOf(...) === 0`
`BigInt` 字面量	⚠️ 慎用	`BigInt('0x' + hex)`
`class`	❌	对象字面量
模板字符串 `${}`	✅	可用
`Buffer`	✅	Node.js 内置
`require`	✅	CommonJS

2.1 Promise.allSettled 替代方案

// ❌ 不支持
Promise.allSettled(promises)

// ✅ 正确写法
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
    }
  }
  throw new Error('all failed')
})

三、搜索结果格式大坑

App 的 MusicListResponse 反序列化要求必须有 list 字段，不是 songs！

3.1 正确的搜索返回格式

return {
  list: [
    {
      id: '歌曲ID字符串',
      name: '歌曲名',
      artists: '歌手1、歌手2',
      albumName: '专辑名',
      albumId: '专辑ID',
      source: 'tx', // tx/kg/kw/wy/mg/git
      pic: '封面大图URL',
      mPic: '封面中图URL',
      sPic: '封面小图URL',
      interval: '3:45', // 播放时长 m:ss
      qualities: {
        standard: '3.21MB',
        exhigh: '7.85MB',
        lossless: '25.3MB',
        hires: '48.2MB'
      }
    }
  ],
  allPage: 5,    // 总页数
  limit: 30,     // 每页条数
  total: 150,    // 总条数
  source: 'tx'   // 平台标识
}

3.2 字段名对照表

含义	正确字段名	错误字段名
歌手	`artists`	`artist`
封面图	`pic` / `mPic` / `sPic`	`picUrl`
时长	`interval` (字符串 m:ss)	`duration`
歌曲列表	`list`	`songs`

四、各平台 API 踩坑记录

4.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 音质参数：API 需要带 k，如 320k，不是 320

4.2 酷狗音乐 (kg)

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

重要：返回字段是 errcode（不是 error_code）！

// ✅ 正确
if (result.errcode !== 0) { ... }

// ❌ 错误
if (result.error_code !== 0) { ... }

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

var picUrl = item.imgurl ? item.imgurl.replace('{size}', '400') : ''

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

4.3 酷我音乐 (kw)

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

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

音质信息：在 N_MINFO 字段中，格式为 level:xxx,bitrate:xxx,format:xxx,size:xxx;...

var parts = info.N_MINFO.split(';')
for (var j = 0; j < parts.length; j++) {
  var m = parts[j].match(/level:(\w+),bitrate:(\d+),format:(\w+),size:([\w.]+)/)
  if (m) {
    if (m[2] === '20900') qualities.jymaster = m[4]
    else if (m[2] === '4000') qualities.hires = m[4]
    else if (m[2] === '2000') qualities.lossless = m[4]
    else if (m[2] === '320') qualities.exhigh = m[4]
    else if (m[2] === '128') qualities.standard = m[4]
  }
}

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

4.4 网易云音乐 (wy)

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

封面图：picId 需要 Base64 编码后拼接

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

getUrl 音质参数：数字格式 128000 / 320000 / 999000（不是带k的）

加密接口：

eapi：AES-128-ECB，key = e82ckenh8dichen8
weapi：AES-128-CBC + RSA（用于需要登录的接口）

ext 功能：

userPlaylist：需要 playlist_url 环境变量（网易云个人主页链接）
dailyRecommend：每日推荐
personalFm：私人FM
myLikedSongs：我喜欢的音乐

4.5 咪咕音乐 (mg)

搜索签名：MD5 拼接

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

封面图：搜索结果可能返回相对路径，需要拼接域名

var img = data.img3 || data.img2 || data.img1 || ''
if (img && img.indexOf('http') !== 0) img = 'https://d.musicapp.migu.cn' + img

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

4.6 GIT音源 (git)

无搜索功能（返回空列表）
纯音源插件，只有 getUrl
getUrl 音质参数：128k / 320k / 999k

五、getUrl 测速容灾逻辑

所有平台统一使用并发测速模式：同时请求多个 API，取第一个成功的结果。

function getUrl(songId, quality) {
  var apis = buildApis(songId, quality)
  var promises = []
  for (var i = 0; i < apis.length; i++) {
    (function(api) {
      promises.push(
        httpGet(api.url, api.headers, 8000).then(function(res) {
          var url = api.extract(res)
          if (url) return { name: api.name, url: url }
          throw new Error('no url')
        }).catch(function(err) {
          throw err
        })
      )
    })(apis[i])
  }
  return 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 ''
  })
}

5.1 音源 API 列表

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

六、版本号管理规范

所有平台统一版本号，每次修改全部升级：

当前版本：0.0.3
下次修改：0.0.4
再下次：0.0.5

文件名格式：Koneko_{平台名}_v{版本号}.js

七、常见报错与解决

报错	原因	解决
`Cannot find module 'axios'`	用了 axios	改用 `http`/`https` 内置模块
`String cannot be converted to JSONObject`	搜索返回了非对象/字符串	加 `.catch()` 兜底返回正确格式
`Field 'list' is required`	搜索返回 `songs` 而非 `list`	改字段名为 `list`
`SyntaxError: Invalid or unexpected token`	用了 `catch { }`	改为 `catch (e) { }`
`FileNotFoundException: plugin.json`	12-4版本需要文件夹结构	创建 `plugin.json` + `index.js`
搜索无结果	字段名不匹配	检查 `errcode` vs `error_code`
播放失败	`mapBr` 返回格式不对	QQ/kg/kw/mg/git 用 `320k`，wy 用 `320000`
封面图不显示	URL 格式错误或跨域	检查各平台封面图拼接规则

八、环境变量

var env = global.env || {}
var CERU_KEY = env.ceru_key || ''      // 聆澜API密钥
var WY_COOKIE = env.cookie || ''        // 网易云Cookie
var PLAYLIST_URL = env.playlist_url || '' // 网易云个人主页链接

在 QZ Music 设置中配置环境变量，插件通过 global.env 读取。

九、完整代码参考

6个平台的完整代码见产物目录：

Koneko_QQ音乐_v0.0.3.js
Koneko_酷狗音乐_v0.0.3.js
Koneko_酷我音乐_v0.0.3.js
Koneko_网易云音乐_v0.0.3.js
Koneko_咪咕音乐_v0.0.3.js
Koneko_GIT音源_v0.0.3.js

十、后续开发建议

每次修改全部平台统一升级版本号
先在浏览器/ curl 测试 API 是否可用
注意 Javet 兼容性，避免现代 JS 语法
搜索返回务必包含 list 字段
getUrl 注意各平台音质参数格式差异
封面图 URL 确保可访问（注意跨域和防盗链）
所有异步操作加 .catch() 兜底
优先使用官方搜索接口，音源用第三方 API 容灾

10 KiB Raw Blame History Unescape Escape

Koneko QZ Music v2 插件开发避坑指南

一、项目背景

1.1 插件加载机制

1.2 插件导出格式

二、Javet/V8 兼容性大坑（最重要）

2.1 Promise.allSettled 替代方案

三、搜索结果格式大坑

3.1 正确的搜索返回格式

3.2 字段名对照表

四、各平台 API 踩坑记录

4.1 QQ音乐 (tx)

4.2 酷狗音乐 (kg)

4.3 酷我音乐 (kw)

4.4 网易云音乐 (wy)

4.5 咪咕音乐 (mg)

4.6 GIT音源 (git)

五、getUrl 测速容灾逻辑

5.1 音源 API 列表

六、版本号管理规范

七、常见报错与解决

八、环境变量

九、完整代码参考

十、后续开发建议

10 KiB

Raw Blame History